Configurable Agent

Turn a single YAML file into a running LLM agent with an HTTP API. You define the system prompt, model, tools, and safety limits; the service runs the tool-use loop and streams every step back to your client over Server-Sent Events.

Works with Anthropic, OpenAI, Google, or any OpenAI-compatible endpoint (including local ollama), connects external tools via the Model Context Protocol, and is built to drop into Kubernetes — config in a ConfigMap, API keys in a Secret.

Quick start

pnpm install
export ANTHROPIC_API_KEY=...          # or OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY
CONFIG_PATH=./example.config.yaml pnpm dev

Send a request and watch the response stream:

curl -N -X POST http://localhost:3000/invoke \
  -H 'content-type: application/json' \
  -d '{"messages":[{"role":"user","content":"search the web for eggai and summarize"}]}'

Documentation

The full User Guide covers:

• Features
• Running
• Configuration
  • Model and providers
  • Prompt templating
  • Tools
  • Structured output
  • Safety: compaction, summarization, and approval
• HTTP API
  • Endpoints
  • Request format
  • Streaming events (SSE)
  • Resolving a tool approval
• Deployment — Docker & Kubernetes
• Observability
• Environment variables

Development

pnpm dev         # run with reload
pnpm test        # run the test suite
pnpm typecheck   # type-check
pnpm lint        # lint / format check
pnpm build       # compile to dist/

Releasing

1. Make sure CHANGELOG.md has entries under [Unreleased].
2. Run the Prepare Release Branch workflow (Actions tab) with the version, e.g. 0.3.1 or 0.3.1-rc.1. It bumps package.json, dates the changelog section, and pushes release/v<version>.
3. Open a pull request from that branch to main (the workflow's job summary has a one-click link and a gh pr create command).
4. Merge it. The Publish to npm workflow then tags v<version>, creates the GitHub release, publishes to npm via trusted publishing, and pushes the container image ghcr.io/eggai-tech/configurable-agent:<version> (plus <major>.<minor> for a stable release).