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-pythonprovider, and when to reach for it instead oflanggraph/crewai/adk - The stdin/stdout JSON contract every custom-python agent must honor
- Declaring agents with a hand-written
.agentvisor/schema.jsonmanifest - 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
- Selection:
mav-agent-config.yamlsetsframework.provider: custom-pythonandframework.command: ["python3", "main.py"] - Execution: AgentVisor spawns
python3 main.pyinside the sandbox, writes the run's input as a JSON object to its stdin, then closes stdin (EOF) - Your code runs:
main.pyreads the JSON, callsrun_agent()— the seam where a real framework would plug in — and prints the result as the last line of stdout - 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.
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
- Custom Agent Frameworks guide: The complete custom-python reference
- LangGraph Chatbot Agent: The same contract, wrapped by the LangGraph provider