> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/configuring-an-agent.md).

# Configuring an agent

An agent definition is a container plus a contract. The contract is what makes it composable: declared input ports, declared output ports, and a fixed convention for how values get in and out of the pod.

## The input and output convention

Inputs arrive as environment variables. An input named `pr_url` is available inside the pod as `$VP_INPUT_PR_URL`, upper-cased and prefixed. Outputs are written to files that the runtime entrypoint collects when the process exits; in the shipped Claude runtime, `/work/output.md` is what gets posted back as the agent's output port.

That convention is the reason the catalog agents look the way they do. The command does its own fetching, hands the model file paths rather than giant argv strings, and writes a single markdown file at the end:

```bash
cd /work && stdbuf -oL -eL claude --dangerously-skip-permissions \
  --verbose -p "$VP_INPUT_DIFF" 2>&1 | stdbuf -oL tee /work/output.md
```

Two details in that line are not decoration. `--verbose` makes the model print turns and tool calls as they happen rather than only the final message, and `stdbuf -oL` forces line buffering so those chunks reach the pod log immediately instead of waiting for a 4-8 KB block. Without both, a running agent looks hung.

Pre-fetching in the command (cloning the repository, checking out the PR, writing the diff to a file) also keeps large inputs out of argv, which is what stops big pull requests failing with `E2BIG`.

## What you fill in

* **Mode**: `agent` or `deterministic`.
* **Driver and model**: for example `claude` and `claude-sonnet-4-6`.
* **Command**: an array, one element per item; typically `bash`, `-lc`, then the script.
* **System prompt**: the role. Keep it about behaviour, not about the task.
* **Agent doc**: markdown mounted into the pod as `/work/CLAUDE.md`. This is where the task, the available inputs, the output format and the "do not write anywhere else" instruction belong.
* **Inputs / outputs**: declared port names, optionally with a schema such as `Diff.v1` or `ReviewResult.v1`.
* **Secrets**: the workspace secrets the pod may see, for example `ANTHROPIC_API_KEY` and `GITHUB_TOKEN`.
* **MCPs**: required servers, with a per-agent method allow-list. Clear it entirely for a stateless agent; a forked manifest can carry entries that only add setup friction.
* **Egress**: the hosts this agent may reach.

{% hint style="danger" %}
**The** `permissions.egress_allow` **block in a catalog YAML is documentation only.** What actually wires the allow-list for a forked agent is the `agents.egress_allow_list` column, written by the post-fork step. When an agent is blocked on an outbound call, check that column, not the manifest that appears to grant it.
{% endhint %}

## Reaching Context Fabric from an agent

Tick the `context-fabric` capability in the agent's configuration and the MCP tools appear, with authentication handled for you. For the upfront context, point the agent doc at the generated file:

```markdown
@@project_workspace/AGENTS.md
```

The first `@` is the model's own directive to pull the file's contents in; `@project_workspace` is an Orchestrator reference that resolves to the shared drive path. The project slug must match between the Orchestrator and Context Fabric, because that pairing is what makes the drive contents line up.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/configuring-an-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.