Skip to content
Octo

Agent Invocation

Agent invocation is an advanced API path for trusted integrations that need to call the agent runtime directly instead of sending traffic through a product entry point.

Key concepts

Section titled “Key concepts”
TermDefinition
Agent invocationA direct call into the agent runtime.
Prompt or messageThe user or system input supplied by the integration.
Runtime contextTenant, space, workflow, channel, or integration metadata supplied with the call.
Tool accessThe set of configured tools available to the invoked agent.

What you can do

Section titled “What you can do”
ActionEndpoint
Invoke an agentPOST /llm-chain/agent/invoke

Invoke an agent

Section titled “Invoke an agent”
Terminal window
curl -X POST "$OCTO_BASE_URL/llm-chain/agent/invoke" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the latest customer request",
    "context": {
      "spaceId": "space_123",
      "workflowVersionId": "workflow_version_123"
    }
  }'

Use this route only when your integration contract explicitly calls for direct agent invocation. Most production channels should use Entry Points so routing, workflow versioning, interactions, and channel behavior stay consistent.

Implementation guidance

Section titled “Implementation guidance”
  1. Keep invocations server-side.
  2. Pass only the context needed for the agent to complete the task.
  3. Confirm which workflow version, tools, and knowledge sheets are available.
  4. Record external correlation IDs in context when you need to reconcile logs later.
  5. Review generated output before using it for irreversible downstream actions.

FAQ

Section titled “FAQ”

Is this the same as executing an AI Workflow? No. Workflow execution runs a graph of stencils. Agent invocation calls the agent runtime directly and should be reserved for integrations that need that lower-level behavior.

Can the invoked agent call tools? Tool availability depends on the runtime context and configured agent permissions. Verify tool access before production use.

Section titled “Related pages”