Run an Agent

Execute a stateless agent request and receive the final answer.

Use a run when you want a single answer without preserving conversation history.

Endpoint

POST /api/v1/agents/{agent_id}/run

{
  "query": "What should I tell a customer asking about refunds?",
  "metadata": {
    "source": "support_tool"
  }
}

The response body contains the final agent output.

Customers can request a refund within the policy window. If the order is outside the window, escalate to the support team for review.

Field	Type	Required	Description
`query`	string	Yes	The instruction, question, or task.
`images`	string[]	No	Image URLs available to the agent.
`documents`	string[]	No	Document URLs available to the agent.
`audios`	string[]	No	Audio URLs available to the agent.
`contexts`	string[]	No	Context IDs available during the run.
`metadata`	object	No	Application metadata.

Keep query specific and include the user-visible task.
Use metadata for routing or trace information, not secrets.
Use threads if the user expects the agent to remember previous turns.
Set timeouts in your application because agent runs can call tools or search knowledge.