Skip to main content
Tools are the bridge between your AI agent and the outside world. This guide covers patterns for integrating external APIs, databases, and services as tools.

Tool Architecture

Basic Tool Handler

Tool Registry Pattern

For larger applications, use a registry:

Integrating REST APIs

HTTP Client Tool

GitHub API Integration

Integrating Databases

PostgreSQL Integration

Rate Limiting

Protect external services from abuse:

Error Handling

Return structured errors for better LLM understanding:

Context-Aware Tools

A tool handler receives the tool name and the arguments. To give tools the context of a run, build the handler for that run and pass it to run():
The context stays on the host: the script cannot read it or change it.

Tool Documentation for LLMs

Generate tool documentation for LLM prompts:

Testing Tools

Best Practices

  1. Validate all inputs - Never trust data from the sandbox
  2. Use typed parameters - Define clear parameter schemas
  3. Return structured data - JSON-serializable results only
  4. Limit data size - Cap array lengths and string sizes
  5. Log all calls - Audit trail for debugging
  6. Handle errors gracefully - Return structured error objects
  7. Rate limit external calls - Protect APIs from abuse
  8. Timeout long operations - Don’t block indefinitely