NovaOS MCP
Field guide

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

  1. 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 skill input_schema.properties.skill.enum.
  2. Uppercase statuses. SkillResult.status in COMPLETED | FAILED | REJECTED | WAITING_USER | AUTH_REQUIRED | QUEUED | RUNNING. Anything else (e.g. "completed") marks the task FAILED.
  3. Input is a string. Parse JSON; service-account callers may double-stringify it; plain text -> treat as {"skill":"chat","text":...}.
  4. Heartbeat at least every 10 s. NovaOS cancels a run after ~30 s without bytes; response headers must arrive within 30 s (stream immediately).
  5. Progress only as platform progress parts. MessageBuilder.embed_progress_message(updater.new_agent_message([]), ProgressMessage(status="in_progress", message=label, progress={"stage": label})) then ctx.task_updater.update_status(TaskState.WORKING, msg). progress must be non-empty for in_progress. Other parts on WORKING updates are dropped or leak. Catch exceptions: after cancel, update_status raises.
  6. 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.
  7. Pods are stateless with a read-only root FS. Only /tmp is 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.
  8. Version sync. Keep AGENT_VERSION in code equal to manifest version (the template test enforces it). Every publish needs a new version.
  9. Never swallow errors into empty results: return SkillResult(status="FAILED", error=...) with a JSON body naming the agent/version.
  10. Logs: use ctx.logger (JSON, bound to run/tenant ids); read them with novaos_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: check ToolResponse.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-servers and "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_image is a platform label matching novaos/base-(plain|langgraph|crewai):X.Y, not your Dockerfile FROM.
  • agent_module = MODULE:ATTR of the AgentBuilder (not the FastAPI app). Publish captures the Agent Card from it and fails on skill drift.
  • permissions.tools: do NOT include memory unless 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_schema values reach the pod as env vars; requiredSecrets install failed on EU staging (SA_AGENT_INSTALL_FAILED).
  • Limits: memory <= 4096 MB, CPU <= 4000 m, timeout <= 600000 ms. release_channel, rollback_policy, dependencies.mcp_servers are 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.