agent-development

Agent Development (cheap-token chat backend)

How to develop the NPA agent chat backend. For operating a deployed agent (deploy/bootstrap/verify, chat UX, API grounding, Rerun) use skills/tools/npa-agent/SKILL.md; for fresh deploy/teardown loops use skills/workflows/agent-fresh-operate/SKILL.md.

Guiding principle: the cheapest token is the one you never spend. Protect and widen the zero-token grounded path; make the unavoidable model calls small, structured, and cheap-model-first.

Architecture (three layers)

1. Grounded intent router (zero tokens) — npa/src/npa/cli/agent_chat.py. match_chat_intent() classifies a turn; build_grounded_reply() answers from live session state with no model call ("grounded": true). Most operator turns end here.
2. Cost-tier routing (cheap model calls) — npa/src/npa/cli/agent_routing.py. Only turns that fall through the router reach Token Factory, and this layer keeps them cheap.
3. Token Factory client — npa/src/npa/clients/token_factory.py (operator/SDK path) and the embedded _provider_chat / _chat_with_resilience in npa/src/npa/cli/agent.py (agent-VM path).

The embedded-backend mechanism (critical)

The agent VM runs backend.py, which is built as one big f-string inside _bootstrap_agent_stack in npa/src/npa/cli/agent.py. Pure helper modules are inlined into it via placeholder substitution — the pattern to reuse when adding logic:

• Real module (normal Python, no brace escaping): agent_chat.py, agent_workflow.py, agent_routing.py.
• Embed helper _embedded_agent_<name>_source() strips the docstring + from __future__ line.
• Placeholder constant _AGENT_<NAME>_EMBED appears in the template and is replaced in the .replace(...) chain near the end of _bootstrap_agent_stack.

Rules:

• Put testable logic in a real module and embed it; do not write new logic directly inside the f-string unless it must touch template variables.
• Code written inside the f-string must escape literal braces as {{ / }} and newlines in strings as \\n; substitutions use single {var}.
• After editing the template, validate the rendered backend compiles (see Testing). A stray brace is a SyntaxError at import of agent.py.
• Embedded routes register before the template's own routes. The _AGENT_*_EMBED placeholders sit earlier in the f-string than most @app.* blocks, and Starlette resolves the first matching route, so an embedded module silently wins over a same-path handler written further down in agent.py. /artifacts/file/{filename} and /artifacts/download each carried two definitions this way, and the shadowed copies in agent.py were the weaker ones — no Content-Disposition/nosniff headers, no run-scoped inventory authorization — so the file a maintainer would open described a contract the deployment did not serve. Before adding a route, grep the embedded modules for its path; test_rendered_backend_registers_no_shadowed_routes fails the build on any method+path registered twice.