Summary

agoda-com/api-agent transforms any GraphQL or REST API into a natural language queryable service, even for operations not directly supported by the API. It targets engineers and power users seeking to query complex data without writing custom code. The agent provides benefits like zero-configuration setup, automatic schema introspection, and powerful SQL-based post-processing for advanced data manipulation.

How It Works

The agent leverages the OpenAI Agents SDK to introspect API schemas (GraphQL or OpenAPI). It translates natural language questions into API calls, storing results in DuckDB for subsequent SQL post-processing. This allows for complex operations such as ranking, filtering, aggregation, and cross-endpoint joins, effectively extending the API's capabilities. A key differentiator is its 'recipe learning' system, which caches successful query pipelines as reusable tools, bypassing LLM reasoning for repeated tasks.

Quick Start & Requirements

Installation can be done directly via uvx, by cloning the repository and running uv sync && uv run api-agent, or using Docker. A primary requirement is an OPENAI_API_KEY. The server runs on a configurable port (default 3000). Configuration involves setting the X-Target-URL and X-API-Type headers to point to the target API's schema or endpoint.

Highlighted Details

• Zero Configuration: Automatically introspects GraphQL schemas or OpenAPI specifications without manual setup.
• SQL Post-processing: Enables complex data operations like ranking, filtering, aggregation, and joins, even if the underlying API does not support them.
• Recipe Learning: Caches successful query pipelines as reusable tools, improving performance and reducing LLM calls for recurring tasks.
• Safety: Operates in read-only mode by default; mutations are blocked unless explicitly permitted via X-Allow-Unsafe-Paths.

Maintenance & Community

No specific details on contributors, sponsorships, or community channels (e.g., Discord, Slack) were found in the provided README snippet.

Licensing & Compatibility

The license type and any compatibility notes for commercial use or closed-source linking are not explicitly stated in the provided README snippet.

Limitations & Caveats

The agent requires an OpenAI API key, making it dependent on an external LLM provider. Learned recipes expire upon schema changes and can be disabled via API_AGENT_ENABLE_RECIPES=false. Unsafe operations (mutations) necessitate explicit configuration.