Extend an Agent
Coding-agent workflow: run as
/extend-agentor by describing the task.
The user names a change; you implement it, verify it against the live agent, and ask if there's more. Stop when they say done. The autonomous half is improve-agent — run it afterward.
The platform is on http://localhost:8000 (RUNTIME_ENV=dev); code edits hot-reload.
0. Preconditions
curl -sSf http://localhost:8000/healthreturns 200 (else ask fordocker compose up -d --build).- The container is bound to this checkout:
docker inspect agentos-api --format '{{range .Mounts}}{{.Source}}{{"\n"}}{{end}}' | grep -F "$(pwd)"prints a line. Empty →cdto the bound repo or restart compose from here. - Ask for the target slug. Suggest a branch:
git checkout -b extend/<slug>-$(date +%Y%m%d).
1. Read the agent
Confirm the slug is code, not a Studio-built component:
curl -s http://localhost:8000/agents | jq -r '.[] | "\(.id)\tis_component=\(.is_component)"'
is_component=true has no source file — route the change through Platform Builder (edit_agent / edit_team / edit_workflow, then publish_component). Never create agents/<slug>.py under that id: code wins on resolution and silently shadows the built component.
Open the file — agents/<slug>.py, or for the reference components platform-builder → agents/builder.py, platform-manager → agents/manager.py, platform-engineer → agents/engineer.py, agno → teams/lead.py. Capture purpose (docstring + INSTRUCTIONS), tools, pattern, and the existing levers (learning=, knowledge=, num_history_runs, model). Restate the purpose in 1–2 sentences.
2. Ask what to change
Structured choice when the harness has one, else plain text. Multi-select is fine — handle sequentially, then loop:
- Add a tool — MCP server, agno toolkit, or function tool.
- Add a capability — knowledge base, learning/memory, sub-agent/context provider, scheduled task.
- Grow the registry — declare a block in
app/registry.pyso everything the platform builds can carry it. Offer this unprompted when the ask is plural ("agents should be able to…"). - Refine instructions — clarify, narrow, change tone or format.
- Fix a bug — ask for the failing prompt, the observed behavior, what they want instead.
- Something else.
3. Ground the change
Search the agno-docs MCP (.mcp.json) for import path, constructor args, required env vars, pip deps. Fallback: https://docs.agno.com/llms.txt. When docs are loose, the installed source settles it:
docker exec agentos-api python -c "import inspect, agno.agent; print(inspect.signature(agno.agent.Agent.__init__))"
docker exec agentos-api python -c 'from agno.tools.exa import ExaTools' # verify EVERY new import in the container
A failing import is a dead platform, not a degraded agent — app/main.py imports every agent at module scope.
Repo-specific rules per branch:
Learning / memory — the lever is
learning=shared_learning(app/learning.py).enable_user_memoriesis not anAgentparameter;enable_agentic_memorymust stay off beside a LearningMachine. Entities are Agno's — don't index them from a second component.add_history_to_contextreplays the session and persists nothing.Knowledge — wire
knowledge=shared_knowledge(app/knowledge.py) as one object (a list on an agent searches nothing). A product agent gets its own base — see create-agent's product pattern.Sub-agent / context provider — mirror
agents/engineer.py: spreadprovider.get_tools()intotools=, appendprovider.instructions()toINSTRUCTIONS.Scheduled task — agno scheduler docs;
scheduler=Trueis already on inapp/main.py.Grow the registry — the bucket you declare into decides how a built component references it (
tool_names,model_id,knowledge_name,learning_name,function_name). Tool names are global to an agent, so a toolkit exposing a name another declared toolkit already has is silently dropped — check first, and give any new toolkitadd_instructions=True(a built component's instructions are model-written; this is your only usage channel):docker exec agentos-api python -c "from app.registry import registry; print([t.name for t in registry.tools if 'read_file' in t.functions])"Refine instructions — propose a minimal diff; narrow ("on recent-events questions, follow up with a
web_fetch") rather than forbid.Fix a bug — reproduce on the live agent first (Step 6), then find the layer:
INSTRUCTIONS(most common), tool, model, env.
4. Propose, then edit
Say in 2–3 lines what you'll change and why; get a "yes". Then edit, one change per loop:
- The component's file — instructions, tools, model,
learning=,knowledge=. app/registry.py— registry branch only; a newapp/<thing>.pywhen the block is more than a constructor call.app/main.py— only for a new sub-agent,knowledge=[...], or interface wiring.app/config.yaml— refresh the description and add a quick prompt that exercises the change.pyproject.toml— only for new pip deps.
5. Restart
docker compose restart agentos-api # no new deps
./scripts/generate_requirements.sh && docker compose up -d --build # new deps
until curl -sSf http://localhost:8000/health > /dev/null; do sleep 0.5; done
docker exec agentos-api grep -c "<unique substring from your edit>" /app/agents/<slug>.py # 0 = edit didn't reach the container
6. Smoke test
Pick a prompt that exercises the change (teams: /teams/agno/runs, same flags):
curl -sS -X POST http://localhost:8000/agents/<slug>/runs \
-F "message=<the targeted prompt>" -F "user_id=claude-extend-agent" -F "stream=false" \
-o /tmp/extend-out.json -w "HTTP %{http_code} in %{time_total}s\n"
jq -r '.content // .' < /tmp/extend-out.json
docker logs agentos-api --since 30s 2>&1 | grep -E "Running: \w+\(" | head -40 # which tools fired
A registry change gets one check first — ask platform-builder: "Call list_tools and show the row for exactly as returned — name, buildable, source. Do not create anything." buildable: true, source: declared means it landed; discovered means it came from boot discovery and a build will refuse it.
Side effects. platform-builder creates and publishes real components on "build me…" prompts, and learning components (agno, platform-manager, platform-engineer, anything with learning=) file what they're told into shared stores. Prefer plan-only probes, use fixture content no real team would have, and bracket the session with the snapshot pairs in improve-agent Step 2. Never run the delete side while someone else is talking to Agno.
Did the change land? Yes → Step 7. Almost → one more pass, at most 2–3, then ask how to proceed. Worse → show git diff and offer to revert only your patch.
7. Loop or wrap up
"Anything else to improve, or are we done?" More → Step 2. Done → Step 8.
8. Report
One line per accepted change, git diff --stat plus the agent-file diff, a suggested commit (feat(<slug>): …, fix(<slug>): …, chore(<slug>): refine instructions), and the next step: improve-agent. A registry change also gets a line in AGENTS.md's registry inventory.