Building agents with the Python SDK
AgentBuilder, the one-skill rule, SkillResult statuses, progress and heartbeats, turn budgets, LLM/MCP/RAG calls inside an agent, manifest v2.0 and Dockerfile rules.
Minimal A2A agent (SDK 2.x)
from fastapi import FastAPI
from novaos_client_sdk import A2A_JSONRPC_PATH, AgentBuilder, AgentExecutionContext, SkillResult
app = FastAPI()
agent = AgentBuilder(name="my-agent", version="0.1.0")
@agent.skill("run", description="...")
async def run(ctx: AgentExecutionContext, input_text: str) -> SkillResult:
return SkillResult(output='{"ok": true}', status="COMPLETED")
app.post(A2A_JSONRPC_PATH)(agent.asgi_endpoint()) # POST "/" JSON-RPC: SendMessage + SendStreamingMessage
NovaOS calls it with header A2A-Version: 1.0 (else JSON-RPC -32009). Tool: novaos_agent_create generates a complete project with contract tests.
How agents are tested: not locally. Before publishing you can only check code contracts (novaos_agent_test), traps (novaos_agent_lint) and that the module loads and skills match (novaos_agent_card). Everything NovaOS gives the agent (execution token, LLM gateway, MCP gateway, RAG, runtime context, progress events) exists only in a NovaOS run. So: publish -> approve -> install -> novaos_test_deployed. Iterate by bumping the version and publishing again.
Rules that save days
- One skill per agent. A multi-skill agent rejects requests that name no skill (
TASK_STATE_REJECTED), and the gateway names a skill only from instance config. Register one skill (run) and dispatch on the input JSON"skill"field; put the operations in the manifest skillinput_schema.properties.skill.enum. - Uppercase statuses.
SkillResult.statusinCOMPLETED | FAILED | REJECTED | WAITING_USER | AUTH_REQUIRED | QUEUED | RUNNING. Anything else (e.g."completed") marks the task FAILED. - Input is a string. Parse JSON; service-account callers may double-stringify it; plain text -> treat as
{"skill":"chat","text":...}. - Heartbeat at least every 10 s. NovaOS cancels a run after ~30 s without bytes; response headers must arrive within 30 s (stream immediately).
- Progress only as platform progress parts.
MessageBuilder.embed_progress_message(updater.new_agent_message([]), ProgressMessage(status="in_progress", message=label, progress={"stage": label}))thenctx.task_updater.update_status(TaskState.WORKING, msg).progressmust be non-empty forin_progress. Other parts on WORKING updates are dropped or leak. Catch exceptions: after cancel,update_statusraises. - Turn budget ~210 s. Streams are cut ~300 s; agent hard cap 600 s (
max_timeout_ms); dispatch can take up to ~80 s before your code runs. - Pods are stateless with a read-only root FS. Only
/tmpis writable; no database in the pod; state goes in the input or through MCP tools to your backend. One pod can serve concurrent runs: keep per-run state in contextvars. - Version sync. Keep
AGENT_VERSIONin code equal to manifestversion(the template test enforces it). Every publish needs a new version. - Never swallow errors into empty results: return
SkillResult(status="FAILED", error=...)with a JSON body naming the agent/version. - Logs: use
ctx.logger(JSON, bound to run/tenant ids); read them withnovaos_agent_logs(agent id, not instance id).
Runtime context
ctx.runtime_context: run_id, thread_id, user_id, tenant_id, instance_id, execution_token, mcp_gateway_url, mcp_gateway_token, gateway_url, config, history, memory_budget, .... Pods also get env vars LLM_GATEWAY_URL, MCP_GATEWAY_URL, MEMORY_SERVICE_URL, CHECKPOINT_SERVICE_URL. Some envs do not send gateway_url in the context: fall back to LLM_GATEWAY_URL. Outside a NovaOS run there is no execution token (MissingExecutionTokenError), which is why testing happens after publishing. ctx.get_secret(name) reads installation secrets (falls back to an env var of the same name).
Calling models (LLM gateway)
async with LLMClient(base_url=gateway_url, execution_context=ctx.to_execution_context()) as client:
raw = await client.chat.completions.with_raw_response.create(
model="gemini-2.5-flash", messages=msgs, extra_body={"disable_fallbacks": True})
resp = raw.parse()
served = raw.headers.get("x-litellm-model-group"); cost = raw.headers.get("x-litellm-response-cost")
Needs novaos-agent-sdk[llm]. ctx.tools.llm does NOT exist (stale scaffold comment). Details: guide 10-llm-gateway.
Calling MCP tools
from novaos_client_sdk.mcp import MCPClient
async with MCPClient(base_url=rc.mcp_gateway_url, headers={"Authorization": f"Bearer {rc.mcp_gateway_token or rc.execution_token}", "X-Tenant-ID": rc.tenant_id}) as mcp:
res = await mcp.tools_call("orbitron-fde.my-mcp.get_status", {})
- Always
async with. Tool names are fully qualified<publisher>.<server>.<tool>;novaos.*are platform tools (novaos.novaos-rag.search,novaos.agents.call,novaos.memory.query). ctx.tools.*bindings (knowledge, agents, files, http, notify, browser, code, connectors, memory) never raise: checkToolResponse.success/.error.- Each MCP hop costs ~1.2-1.5 s: reuse one client per run; add composite read tools.
- In USER runs, write-named tools are refused with -32042: see guide
04-mcp-serversand "returned writes" below.
RAG search inside an agent
novaos.novaos-rag.search with {"collection_id", "query", "top_k", "use_decomposition": false, "use_expansion": false}. Dedupe hits by chunk id, rerank with a cheap model, never threshold scores. Never ingest from the agent; never call query on a latency path. Guide 05-knowledge-rag.
Returned writes (user runs)
User-scoped runs cannot call write-classified MCP tools. Pattern: the backend sends "persistence": "return" in the input; the agent reads through read-named tools only, collects writes, and returns them in the result TEXT as {"v":1,"encoding":"zlib+base64+json","data":...} (cap ~4 MB); the backend applies them for the user's org before passing the answer on. Helper: encode_writes() in the template.
Manifest v2.0 essentials
{"schema_version":"2.0","name":"my-agent","version":"0.1.0","protocol":"A2A","agent_module":"server:agent",
"publisher":"<your-slug>","language":"python","base_image":"novaos/base-plain:1.0",
"permissions":{"tools":["llm"],"models":["llm:model:*"],"max_memory_mb":1024,"max_cpu_millicores":1000,"max_timeout_ms":600000},
"deployment_target":["chat"],
"skills":[{"name":"run","input_schema":{"type":"object","properties":{"skill":{"enum":["ping","chat"]}}}}]}
base_imageis a platform label matchingnovaos/base-(plain|langgraph|crewai):X.Y, not your Dockerfile FROM.agent_module=MODULE:ATTRof the AgentBuilder (not the FastAPI app). Publish captures the Agent Card from it and fails on skill drift.permissions.tools: do NOT includememoryunless you use it (SDK then prefetches Memory before every turn).deployment_target:["chat"]lists it in the marketplace;["api"]only via Admin > Agent Catalog (for service accounts).installation_config.config_schemavalues reach the pod as env vars;requiredSecretsinstall failed on EU staging (SA_AGENT_INSTALL_FAILED).- Limits: memory <= 4096 MB, CPU <= 4000 m, timeout <= 600000 ms.
release_channel,rollback_policy,dependencies.mcp_serversare silently stripped by CLI 2.2 validation.
Dockerfile rules
Non-root user (uid 1001), ENV TMPDIR=/tmp HOME=/tmp, EXPOSE 8001, CMD uvicorn server:app --host 0.0.0.0 --port 8001, RUN python -c "import server" to fail the build on import errors, do not .dockerignore *.md if prompts are markdown. Shared code outside the agent folder: publish with --context .. and COPY relative to that context.
Tools: novaos_agent_lint checks all of the above automatically.