Running agents from chat

v2.9.2 — ask the Operations Assistant for a starter-kit agent and copy-paste it onto your own machine. Traces land back in /traces tagged with a correlation id so you can see the chat-to-trace link.

AuditTrail never runs your agent for you. Agents run on your infrastructure — your laptop, your container, your CI. This keeps credentials, dependencies, and networking fully under your control. The chat integration exists to remove the "where do I start?" paper-cut: it generates a working file you can paste and run in under a minute.

The flow

1. Open the Operations Assistant.
2. Ask for a template, e.g.:
   • "Give me a deep-search agent for 'recent LLM benchmarks'"
   • "Spawn a quick-chat template"
   • "I want a tool-calling demo"
3. The assistant replies with an Agent template tile listing the matching starter kits and their required env vars.
4. Click a template, enter the prompt you want the agent to run, hit Render. The API returns a bundle of files with your AUDITTRAIL_API base URL and a fresh correlation_id already baked in.
5. Copy the files into a folder on your machine, fill in your provider key + AUDITTRAIL_API_KEY, and run:

   bash

   Copy

   pip install -r requirements.txt
   python agent.py

6. Traces show up in /traces under agent name <template-id>-<correlation_id> (e.g. deep-search-ab12cd34).

Available templates

The catalog is backed by GET /api/v1/agent-templates; the assistant calls this when it sees a spawn-intent phrase (run an agent, spawn, give me a template, starter kit, etc.).

Why correlation ids?

Every render generates a short hex correlation id. The rendered snippet bakes it into AUDITTRAIL_AGENT_NAME so your local run's traces carry the id through the normal ingest path. The chat tile then polls GET /api/v1/agent-templates/proposals/{correlation_id} and updates from "awaiting" to "observed" as soon as your traces arrive — giving the chat-to-trace link without any extra infra on your side.

Why not just run it server-side?

Three reasons:

1. Keys stay with you. We never see your OpenAI key, never proxy your calls, never store your credentials. Your agent talks directly to its LLM provider; AuditTrail just observes the telemetry.
2. Your environment. Your retrieval stack, your vector DB, your custom tools, your enterprise proxy — none of those translate into a hosted runtime. Copy-paste into your actual dev environment sidesteps the "works in the playground, not in prod" trap.
3. Security. A hosted agent-runner would need a daemon, auth tokens, firewall whitelisting, outbound network policies. That's real engineering + a real attack surface. The copy-paste flow gives you the same UX with zero of that.

If you do want a hosted runner, the examples/ directory has the same templates as standalone projects — deploy one of those to your own compute and point it at this API.

Customising templates

The template library is currently a small Python registry (audittrail.agent_templates). If you want your own templates available in chat for your whole org, open a PR adding a new AgentTemplate(...) entry. A future release will move this into a per-tenant YAML file so you can manage it without a code deploy.

Troubleshooting

Nothing appears in /traces after I run the snippet. Double-check that AUDITTRAIL_API points at the same host you're viewing the dashboard on, and that AUDITTRAIL_API_KEY is a valid ingest-scoped key. curl $AUDITTRAIL_API/api/v1/health should return 200 from your laptop.

The correlation poll endpoint says "awaiting" forever. Your run didn't ingest any traces yet. Check the local terminal running python agent.py for errors — the most common cause is a forgotten at.flush() at the end of the script (every template ships with this line; don't delete it).

Can I skip the chat and render directly? Yes — POST /api/v1/agent-templates/{id}/render with {"prompt": "..."} works with the normal API-key auth, no chat involved.