AI Agents

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Orqestra supports agentic execution through the agent flow step. An agent step receives a goal, optionally calls tools, and loops until it returns a final answer or reaches its iteration limit.

Current Product Model

There are two related but distinct concepts:

1. Agent step The runtime primitive that actually executes an agent loop inside a flow.
2. Agent asset A governed asset kind used to version and manage agent definitions as product artifacts.

The current runtime executes agent behavior from the flow step payload (goal, tools, system_prompt, max_iterations) plus the release-bound model_policy, prompt_template, and optional guardrail_config.

The current docs should not treat agent assets and agent steps as the same runtime contract.

Agent Step Fields

These are the fields that matter most for the current agent step:

If a model_policy binding is missing from the active release, provider-routed agent steps cannot run successfully.

Example Agent Step

steps:
  - id: research
    type: agent
    goal: "Research {{trigger.topic}} and summarise the result"
    system_prompt: "You are a concise research assistant. Cite sources when available."
    tools:
      - http_request
      - github_api
      - spawn_subagent
    max_iterations: 6
    next: respond
 
  - id: respond
    type: return
    output:
      answer: "{{steps.research.output.content}}"
      tools_called: "{{steps.research.output.tools_called}}"
      turns_used: "{{steps.research.output.turns_used}}"

Agent Output Shape

The runtime records structured agent output like this:

{
  "content": "Final answer text",
  "turns_used": 2,
  "tools_called": ["github_api"],
  "reasoning_trace": [
    {
      "turn": 1,
      "action": "tool_call",
      "tool": "github_api",
      "inputs": { "operation": "search_issues" },
      "output": { "results": [] }
    },
    {
      "turn": 2,
      "action": "final_answer",
      "content": "Final answer text"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 44,
    "total_tokens": 164
  }
}

The reasoning trace is also persisted as an evidence artifact.

Built-In Multi-Agent Pattern

An agent step can orchestrate child flows by calling the built-in spawn_subagent tool. This is the current supported multi-agent pattern.

Use it when:

• one agent needs to delegate to specialist child flows
• you want child executions with their own evidence and retrieval events
• you want the parent execution to retain the full reasoning trail

When you specify tools, include spawn_subagent explicitly if you want the agent to use it.

Agent Assets

agent is also a governed asset kind. The current public schema for an agent asset looks like this:

{
  "name": "research-agent",
  "description": "Research-oriented assistant for governed workflows",
  "persona": "You are a thorough but concise research assistant.",
  "permitted_tools": ["http_request", "github_api", "spawn_subagent"],
  "model_config_ref": "research-model-config",
  "reasoning_config": {
    "max_iterations": 8,
    "temperature": 0.2,
    "tool_selection": "allowed_only"
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" }
    }
  }
}

Treat agent assets today as governed definitions and release artifacts. The runtime agent step still depends on the step-local execution fields shown above.

Prompt Caching

Orqestra supports prompt caching across providers to reduce cost on multi-turn agent flows. For flows with three or more tool turns, caching typically reduces prompt token costs by 60–90%, which are the dominant cost in agent loops.

For Anthropic models, set ORQESTRA_PROMPT_CACHING_ENABLED=true on the runtime-gateway to enable explicit cache hints. OpenAI and DeepSeek apply caching automatically with no operator action required.

Memory And Guardrails

Agent steps can participate in workload-bound memory and guardrail behavior:

• Memory If a memory asset is bound to the active release and the request carries actor/session context, prior memory entries are injected automatically.
• Guardrails If a guardrail_config asset is bound to the active release, the runtime evaluates the agent goal before execution and the final content after execution.

These are workload/release concerns, not per-step nested config blocks.

Best Practices

Prefer a short tool list. Agents behave more predictably when the tool surface is intentionally narrow.

Use llm_call unless you need tool selection or iterative reasoning. The agent step is more flexible, but it is also more expensive and harder to reason about operationally.

Bind model_policy, prompt_template, policy_bundle, and guardrail_config consistently. Agent steps are only safe when the release context is complete.

Use spawn_subagent for supervisor patterns. Do not invent nested supervisor-only flow fields when the runtime already supports child-flow orchestration through the built-in tool.