Skip to main content

Minimal Agent

The smallest possible agent that runs under AgentVisor: a Python script that reads a JSON object from stdin and writes a JSON object to stdout, with no agent framework at all.

Difficulty: Basic

What You'll Learn​

  • The custom-python provider, and when to reach for it instead of langgraph/crewai/adk
  • The stdin/stdout JSON contract every custom-python agent must honor
  • Declaring agents with a hand-written .agentvisor/schema.json manifest
  • The smallest working MPE policy domain in the repo

Setup​

agentvisor template create custom-python/minimal-agent
cd minimal-agent

temporal server start-dev &
agentvisor serve . --sandbox=none

Test It​

THREAD=$(curl -sX POST http://localhost:8090/threads | jq -r '.thread_id')

curl -sX POST "http://localhost:8090/threads/$THREAD/runs?wait=30s" \
-H "Content-Type: application/json" \
-d '{"input": {"message": "Hello!"}}' \
| jq '.output'

The agent echoes the input back: {"reply": "You said: Hello!"}.

How It Works​

  1. Selection: mav-agent-config.yaml sets framework.provider: custom-python and framework.command: ["python3", "main.py"]
  2. Execution: AgentVisor spawns python3 main.py inside the sandbox, writes the run's input as a JSON object to its stdin, then closes stdin (EOF)
  3. Your code runs: main.py reads the JSON, calls run_agent() — the seam where a real framework would plug in — and prints the result as the last line of stdout
  4. Output: AgentVisor reads the last stdout line as the run's JSON output; the process exits 0

The stdin/stdout Contract​

main.py reads one JSON object from stdin and prints one JSON object as the last line of stdout, with logs on stderr. The exact rules — exit codes, what happens to a malformed last line, and the environment variables AgentVisor injects — are in The Agent Process Contract.

Where To Plug In Your Framework​

main.py's run_agent() function is the only thing you need to replace — swap its body for a call into your proprietary framework. Everything around it (stdin read, JSON parse, stdout write, exit code) is the fixed contract.

Declaring the Agent​

Because there's no langgraph.json/crewai.yaml/agent.yaml to discover, the agent is declared by hand in .agentvisor/schema.json:

{
"version": "1.0",
"graphs": {
"minimal_agent": {
"name": "minimal_agent",
"description": "Echoes the input message back in its reply.",
"input_schema": {
"type": "object",
"properties": { "message": { "type": "string" } },
"required": ["message"]
},
"output_schema": {
"type": "object",
"properties": { "reply": { "type": "string" } },
"required": ["reply"]
},
"metadata": {}
}
}
}

Without this manifest the agent still runs — it's just absent from GET /agents, has no MCP invoke_agent tool, and no A2A skill card entry.

Known limitation

GET /agents currently lists this agent only under --sandbox=none. Under --sandbox=docker/--sandbox=gvisor, the agent still runs correctly end-to-end — only discovery (GET /agents, MCP invoke_agent, the A2A skill card) is affected, because the hardened sandbox hides the build-time .agentvisor/schema.json. This applies to every agent that relies on a build-time manifest, not just this example.

Policy Model​

The policy (policies/domain.yml) is the smallest working MPE policy domain in the repo: it grants the core AgentVisor resources (threads, runs, state, agents, store) to authenticated principals and denies everything else by default. There's no HTTP allowlist because this agent makes no outbound calls.

Project Files​

minimal-agent/
├── main.py # Agent entrypoint: stdin -> run_agent() -> stdout
├── mav-agent-config.yaml # framework.provider: custom-python
├── requirements.txt # Python dependencies (none -- stdlib only)
├── .agentvisor/
│ └── schema.json # Hand-written agent schema manifest
└── policies/
├── domain.yml # MPE PolicyDomain (core resources only)
└── test.yml # Policy test cases

Next Steps​