`agent://`¶

Invoke a Helix agent from inside a route. The producer takes the exchange body as the user message, runs the registered (or ad-hoc) agent through the ADK runtime, and writes the agent's reply back onto the exchange. Reach for agent:// when you want LLM reasoning, tool-calling, or multi-step planning as a step in an integration pipeline.

URI shape¶

agent://<agent-id>?<params>

<agent-id> is mandatory. Two resolution modes:

Registered agent: if an *adk.Agent is already registered under agent-id (e.g. defined in the workflow YAML, or attached programmatically), it is used as-is and only the path is consulted.
Ad-hoc agent: if no agent is registered for the ID, one is constructed lazily from the URI params. model and modelName are required for this mode.

Agents are producer-only — CreateConsumer returns an error. Wire agents as to: targets (or behind a tool:// / route trigger), never as a from: source.

Parameters¶

Param	Type	Default	Producer/Consumer/Both	Description
(path) `agent-id`	string	required	Producer	Agent identifier. Looked up in the component's registry first; falls back to ad-hoc creation.
`type`	enum	`react`	Producer	Ad-hoc agent type: `react`, `supervisor`, `sequential`, `parallel`, `loop`, `plan-execute`, `deep`.
`model`	string	—	Producer	Ad-hoc only — LLM provider name (`openai`, `anthropic`, `ollama`, etc.). Required when the agent is not pre-registered.
`modelName`	string	—	Producer	Ad-hoc only — concrete model id (`gpt-4o`, `claude-sonnet-4-20250514`, ...). Required when the agent is not pre-registered.
`apiKey`	string	—	Producer	Ad-hoc only — API key passed to the LLM provider.
`baseURL`	string	—	Producer	Ad-hoc only — override the LLM provider base URL.
`systemPrompt`	string	—	Producer	Ad-hoc only — system prompt for the new agent.
`maxIterations`	integer	`10`	Producer	Ad-hoc only — ReAct loop cap.

Headers¶

Read by the producer¶

Header	Type	Effect
`HelixStream`	string (`"true"`)	Switch to streaming mode. Body becomes a `*llm.StreamReader` for downstream SSE / chunked delivery. `Content-Type` is set to `text/event-stream`.
`systemPrompt`	string	Per-call system-prompt override. Prepended to the user message as `[System Context: ...]`.

Written by the producer¶

Header	Description
`agent.invocation_id`, `X-Helix-Invocation-Id`	Random 16-char hex ID for the running call. Surface in HTTP responses so operators can cancel it via the management API.
`agent.id`	The agent ID actually used.
`agent.type`	Agent orchestration type (`react`, `supervisor`, ...).
`agent.model`	`provider/modelName` (ad-hoc mode only).

The user message comes from ex.In().BodyAsString(). If the exchange carries multipart content (images, audio, files attached via exchange.SetMultipartBody), the producer extracts text parts to build the user message and forwards the binary parts as llm.ContentPart to the agent via RunWithParts / QueryStreamMultimodal.

Examples¶

Invoke a registered agent:

workflows:
  - id: classify
    trigger: { uri: direct://classify }
    steps:
      - target: agent://sentiment-classifier

Ad-hoc agent (no pre-registration needed):

workflows:
  - id: ask-gpt
    trigger: { uri: direct://ask }
    steps:
      - target: agent://q?model=openai&modelName=gpt-4o&apiKey=${OPENAI_API_KEY}&systemPrompt=Answer+concisely

Streaming with HTTP delivery:

workflows:
  - id: chat-sse
    trigger:
      uri: http-server://0.0.0.0:8080/chat
    steps:
      - set-header:
          name: HelixStream
          constant: "true"
      - target: agent://assistant

Cancel a running invocation from the management API:

curl -X POST http://helix:9000/api/v1/agents/invocations/$INVOCATION_ID/cancel \
  -H 'Content-Type: application/json' \
  -d '{"reason":"user_aborted","actor":"alice@example.com"}'

Behavior notes¶

Pause / kill-switch / cancel — the component supports per-agent pause, a global kill-switch, and per-invocation cancel. All three abort in-flight calls by canceling the contexts stashed via trackInvocation. When a PauseStore is attached (Redis backend), pause / resume / cancel events are broadcast across the cluster.
Budgets — WithBudget(agentID, *adk.Budget) and per-tenant variants throttle invocations or LLM spend. Exceeded budgets auto-pause the agent (or the tenant slice of it). The producer enforces tenant invocation quota via AddInvocation before each call.
Multimodal — see pkg/exchange/multipart.go. Set exchange.SetMultipartBody(ex, ...parts) upstream to deliver images / audio / files.
Exchange-aware prompts — the producer stashes the inbound exchange in the context (adk.WithExchange) so prompt templates can read {{ headers.X-Tenant-ID }}-style references.
Registered vs ad-hoc — registered agents are constructed once (typically at engine boot from agents: YAML); ad-hoc agents are built per-endpoint and cached.

Source¶

pkg/component/agent/agent.go, pkg/component/agent/controller.go, pkg/component/agent/budget.go, pkg/component/agent/pausestore.go, pkg/component/agent/redisstore.go

agent://¶