Runs
Runs execute one agent request without preserving chat history.
A run is a single execution of an agent. It takes an input, uses the agent's configured resources, and returns an output.
When To Use Runs
Runs are best for:
- Classifying or summarizing one item.
- Generating a response for a backend workflow.
- Processing a form submission.
- Testing an agent without creating a chat history.
Runs vs Threads
| Feature | Run | Thread |
|---|---|---|
| Stores chat history | No | Yes |
| Best for | One-off tasks | Multi-turn chat |
| Typical endpoint | /run | /stream/threads |
| Returns | Final output | Streamed events and conversation state |
Inputs
Runs can include a query, file URLs, context IDs, and metadata. Keep metadata structured and avoid sending secrets.