Skip to content

Agents and prompts

English translation pending

Full content currently exists only in Russian. Use the language selector at the top of the page → Русский. The summary below covers the essentials.

AI is a scalpel, not a sledgehammer (VISION). An agent in Axon is a workflow function: a workflow whose config shape is agent_config (or a reference to a reusable AgentDefinition via agent_ref). It runs through the same WorkflowRunner and passes the same policy / budget / approval gates as any other step.

1. What it is and why

  • PromptVersion (table app.prompt_versions, id prefix pver_<ulid>) — versioned prompt template with placeholders. PROMPT-SCOPE.
  • AgentDefinition (table app.agent_definitions, id prefix agdef_<ulid>) — versioned AgentSpec with pinned prompt_version_id (not key:latest). AGENTSPEC + AGENTS-FINISH.
  • Both are append-only versioned for replay determinism. Runtime/replay only accepts pinned ids (no key:latest at runtime).
  • All LLM calls go through LiteLLM proxy via Pydantic AI / Instructor. Direct provider SDKs are forbidden in business logic (CLAUDE.md).
  • An agent is not a separate service, not a separate execution process, and not a license to bypass policy/approval gates.

2. Roles and access

Action Permission owner admin manager operator reviewer read_only system
Publish/archive/set-active prompt version prompt:manage ✅ ✅ ❌ ❌ ❌ ❌ ✅
Publish/archive AgentDefinition agent_definition:manage ✅ ✅ ❌ ❌ ❌ ❌ ✅
Read prompts / agents read ✅ ✅ ✅ ✅ ✅ ✅ —

Manager does not have prompt:manage / agent_definition:manage: prompt content is part of the code surface (engineers author, owner/admin publish). system is granted for the seed-on-create-project flow. All mutations go through CommandEnvelope (sync_apply) — backdoor SQL is forbidden.

3. Where in Console

  • Prompts (/{project_id}/prompts or /admin/prompts): list / detail / history / publish-new-version / archive / set-active.
  • Agents (/{project_id}/agents or /admin/agents): list / detail / history / publish-new-version / archive.

Console reads only via query API over read.prompt_versions / read.agent_definitions projections — never app.* directly.

4. Concepts

  • Scope — instance (project_id IS NULL) or project. Project-scope entry shadows an instance-scope one with the same key. For output_schema_ref shadowing is explicit only — silent fallback to instance is forbidden (output_schema_ref_instance_scope_not_allowed).
  • Pinning — authoring uses key:* refs; materialization boundary (publish_definition, create_workflow, edit_workflow) replaces them with pinned agdef_* / pver_*. Runtime/replay accepts pinned only.
  • AgentSpec tool exposure rule (ARCHITECTURE-V6 §11) — direct agent tools are restricted to side_effect_class="none" ∩ project enabled_tools ∩ executor profile allowed_tools. internal/external_* actions are workflow steps (tool_call/external_write) with policy gate, not direct agent tools.
  • Output schema XOR — AxonAgentSpec must declare exactly one of output_fields / output_schema_jsonschema / output_schema_python. output_schema_python is forbidden for origin='user' specs.
  • UPGRADE_CHAIN (adaptive routing) — cheap-by-default, escalate on validator failure: haiku → sonnet → opus (core/ai/model_router.py). Each call (including failed) records selected_model, complexity_score, routing_mode in budget_ledger. Invariant I-DOMAIN-AGENTSPEC-ROUTING-UPGRADE-CHAIN (AGENTS-FINISH Bundle B).
  • Validator retry-with-feedback — pydantic_output phase retries with feedback up to retries (0–5); post_acceptance phase only logs. Invariant I-DOMAIN-AGENTSPEC-VALIDATOR-RETRY-FEEDBACK (Bundle C).
  • No code-owned fallback seeds — built-ins seed only via migrations 040–041 (system actor); built_in_specs.py was removed (Bundle A invariant I-DOMAIN-AGENTSPEC-NO-CODE-FALLBACK-SEEDS). AgentSpecResolver raises LookupError on miss; AgentPromptResolver no longer accepts fallback:*.

5. Flows

  1. Create a prompt in a project — Prompts → + New prompt → fill content + placeholders → publish_prompt_version. Pre-accept secret scan rejects token-like strings. The prior active version with the same (scope, project, key) is auto-archived.
  2. Publish AgentDefinition — write AxonAgentSpec in code / Console form → publish_agent_definition. Handler validates XOR output schema, scope contract, input builder contract, deps_overrides safety, resolves prompt to pinned pver_*, inserts agdef_<ulid>, archives the prior active.
  3. Use AgentDefinition in a workflow — Step(step_type="model_call", config={"agent_ref": "key:email_classifier", ...}). axon push materializes key:* → agent_definition:id:agdef_*. Runtime accepts only pinned form.
  4. Use output_schema_ref for a model_call — output_schema_ref="agent_definition:key:<key>". Materialized into pinned form; silent fallback to instance scope rejected.
  5. Rotate a prompt — Publish new version → old auto-archived. Existing AgentDefinitions keep pointing at the pinned old pver_*; to use the new version, publish a new AgentDefinition.
  6. Grant agent access to a new direct tool — tool must be side_effect_class="none", in project enabled_tools, in executor_profile.allowed_tools; then add tool_keys in a new publish_agent_definition.

6. Options reference

See the Russian manual §6 for the full field reference of PromptVersionSpec (MAX_PROMPT_CONTENT_LENGTH=32_000, MAX_PLACEHOLDERS_PER_PROMPT=32, etc.) and AxonAgentSpec (output schema XOR, retries: 0..5, tool_keys unique, scope contract, deps_overrides safety). Command surface: publish_prompt_version / archive_prompt_version / set_prompt_version_active (target prompt_version, prompt:manage); publish_agent_definition / archive_agent_definition (target agent_definition, agent_definition:manage); all sync_apply.

7. Lifecycle and operations

  • Per-project seed. create_project handler calls ensure_project_seed_agent_definitions() in the same transaction; PROJECT_AGENT_SEEDS covers triage/planner/reviewer/conversation. monitor is seeded instance-scope.
  • Versioning. Append-only. Exactly one active per (scope, project_id, key); the rest archived. Archived rows survive for compliance and replay pin safety.
  • Pin-protection on archive_prompt_version: rejected if the prompt version is pinned by any active AgentDefinition. Publish a new AgentDefinition first.
  • Reactivation. set_prompt_version_active(pver_X) allowed; no pin-protection (replay pins keep working through id).
  • Observability. Langfuse trace per LLM call (prompt_version_id, agent_definition_id, selected_model, complexity_score, validator outcomes); budget_ledger row per call.

8. Troubleshooting

Symptom Cause Fix
publish_prompt_version → 422 «secret-like string» pre-accept secret scan tripped Remove the literal token / API key / credential URL
archive_prompt_version → 409 prompt_pinned_by_active_agents Some active AgentDefinition pins this prompt version Publish a new AgentDefinition without that pin, then retry
publish_agent_definition → 422 «exactly one of output_fields/jsonschema/python required» XOR violated Pick one
publish_agent_definition → 422 «output_schema_python forbidden for user-origin» user-origin pointing at a Python class Use output_fields or output_schema_jsonschema
publish_definition → output_schema_ref_instance_scope_not_allowed Project workflow refers to AgentDefinition by key:*, no project-scope row exists Publish AgentDefinition in this project, or use explicit agent_definition:id:agdef_*
Agent ignores a tool Tool not side_effect_class="none", or not in project enabled_tools, or not in executor_profile.allowed_tools Fix the failing gate
Operator wants an audited read tool Requires a separate public contract (no implicit rule) Use tool_call step with policy gate, or open a new backlog item
Adaptive routing keeps escalating to opus Validator keeps failing or complexity estimated very high Check Langfuse; tighten prompt/schema/validator; or force routing_mode='fixed'

9. Constraints and invariants

  • No code-owned fallback seeds (I-DOMAIN-AGENTSPEC-NO-CODE-FALLBACK-SEEDS).
  • Upgrade chain order haiku → sonnet → opus (I-DOMAIN-AGENTSPEC-ROUTING-UPGRADE-CHAIN).
  • Validator retry-with-feedback semantics by execution phase (I-DOMAIN-AGENTSPEC-VALIDATOR-RETRY-FEEDBACK).
  • Pinning is mandatory at runtime / replay for agent_ref and output_schema_ref.
  • AgentSpec tool exposure rule — direct agent tools are none only; project allowlist; executor profile cap.
  • Output schema Python class — system/code origin only.
  • Secrets never appear in prompts (pre-accept scan).
  • Scope contract — project ⇔ project_id required; instance ⇔ project_id IS NULL; no cross-project leak.
  • No silent shadowing for output_schema_ref to instance scope.
  • AI is not mandatory at any level (VISION); workflows without agents are first-class.