Skip to content

ADR 0004: No HTTP API in this project

Status: accepted (v0.1.0)

Context

An agent that answers database questions invites an HTTP wrapper. An HTTP surface brings authentication, request limits, tracing, per-caller budgets and multi-tenant concerns, none of which are what this project is meant to demonstrate. In the wider portfolio a separate gateway project is planned to own those concerns for several services.

Decision

The only public entrypoint is the library function db_action_agent.run.run(question) -> AgentResult. The only interface shipped is the CLI, db-agent ask "<question>", which calls run() and nothing else. There is no server, no listener and no exposed port for the agent (the compose file publishes only Postgres, on host port 5433).

Each run() is one independent question: there is no conversation state.

Consequences

  • No throwaway HTTP layer to maintain or secure, and no auth story to get wrong.
  • A gateway or service wrapper can be built later by importing run(); the result is a plain dataclass (summary, chart, sql_log, hop_count, failed).
  • Honest limits. Nothing here provides rate limiting, per-user budgets, request tracing or cost caps beyond the per-run hop and retry ceilings. run() does not currently translate infrastructure failures (missing API key, Anthropic API errors, database connection errors) into a failed result: they surface as raw exceptions at the CLI. The database engine is a process-wide singleton created from AGENT_DATABASE_URL, which suits a short-lived CLI process and would need revisiting inside a long-running service.