Message Basics
Every conversation with the Agent API consists of messages with roles:Structuring User Messages
Be Specific, Not Vague
- ✅ Specific
- ❌ Vague
Break Down Complex Requests
For multi-step tasks, use numbered lists:Provide Context When Relevant
Use Formatting for Clarity
Markdown formatting helps with complex inputs:Handling Tool Results
When providing tool results back to the agent, format them clearly:Simple Results
Structured Results
For complex data, use JSON or formatted text:Error Results
When a tool fails, provide helpful error information:Multi-Turn Conversation Patterns
Pattern 1: Clarification Flow
When the agent needs more information:Pattern 2: Iterative Refinement
When building on previous results:Pattern 3: Multi-Tool Workflow
When multiple tools need to work together:Providing Examples in Messages
For complex tasks, include examples in your request:Managing Context Length
Keep Messages Focused
Long conversation histories can overwhelm the model. Periodically summarize:Trim Irrelevant Details
Quick Reference
| Scenario | Best Practice |
|---|---|
| Complex requests | Use numbered lists |
| Data input | Use tables or JSON |
| Tool results | Include key data, omit noise |
| Errors | Provide context and suggestions |
| Long conversations | Summarize periodically |
| Examples needed | Show input → output format |
Next: Common Patterns →
