Skip to main content

Your first governed agent

In this tutorial we will get from zero to a policy-enforced AI agent in one path: install Talon, initialize a project, configure an LLM key, run a query, and see evidence recorded. By the end you will have run a governed agent and seen the audit trail.

Prerequisites: Go 1.22+ with CGO (or a linux/amd64 release tarball), and an LLM API key (OpenAI or Anthropic) or a local Ollama instance for live runs. Dry-run works without an API key.

1. Install Talon​

See the README install matrix for all methods. macOS and arm64 Linux: use from-source or go install (prebuilt GitHub tarballs are linux/amd64 only).

# Recommended on macOS / arm64
git clone https://github.com/dativo-io/talon.git && cd talon
make install   # → $(go env GOPATH)/bin/talon

# Or: go install github.com/dativo-io/talon/cmd/talon@latest

macOS: If linking fails with unsupported tapi file type '!tapi-tbd', use make install or CC=/usr/bin/clang CGO_ENABLED=1 go install github.com/dativo-io/talon/cmd/talon@latest.

Check that it works:

talon --help

You should see the list of commands.

2. Initialize a project​

Create a new directory and run talon init. In a terminal, this starts the interactive wizard: you answer a few questions (workload type, framework pack, LLM provider, data residency, compliance features) and Talon generates both config files.

mkdir my-agents && cd my-agents
talon init

You will see two files created:

  • agent.talon.yaml — agent policy (owned by governance/compliance team). Defines what the agent is allowed to do: cost limits, PII detection, model routing, compliance declarations.
  • talon.config.yaml — infrastructure config (owned by DevOps/platform team). Defines how Talon runs: LLM provider connections, gateway settings, storage paths.

Other ways to init (no wizard):

  • talon init --scaffold — quick defaults (good for scripts or CI).
  • talon init --pack openclaw (or fintech-eu, etc.) — starter pack for a specific use case.
  • talon init --name my-agent --owner you@company.com — use with --scaffold or after the wizard to set name and owner.

3. Configure an LLM provider​

Talon needs an API key to call the LLM. For this tutorial we use an environment variable.

export OPENAI_API_KEY=sk-proj-...
# Or: export ANTHROPIC_API_KEY=ant-...
# Or: nothing needed for Ollama (runs on localhost:11434)

First run without AWS? The default template may set tier_2 to a Bedrock-only model. If you only have OpenAI or Anthropic, either run the wizard and pick a provider that fits, use talon init --pack telecom-eu in a new directory, or edit agent.talon.yaml: set policies.model_routing.tier_2.bedrock_only: false and set primary to e.g. gpt-4o or gpt-4o-mini. Otherwise tier-2 requests will fail.

4. Run your first agent​

Run a single query. Talon will load policy, classify input, evaluate policy, call the LLM, and store evidence.

talon run "Summarize the key trends in European AI regulation"

You should see output like:

✓ Policy check: ALLOWED

The European Union has been at the forefront of AI regulation...

✓ Evidence stored: req_xxxxxxxx
✓ Cost: €0.0018 | Duration: 1250ms

Notice the evidence ID (e.g. req_xxxxxxxx). Every run produces a signed audit record.

5. Try a dry run​

See the policy decision without calling the LLM:

talon run --dry-run "What is the company revenue?"

You should see: ✓ Policy check: ALLOWED (dry run, no LLM call).

6. Try a policy block​

Edit agent.talon.yaml and set a very low daily budget:

policies:
  cost_limits:
    daily: 0.001

Run again:

talon run "Summarize EU regulation trends"

You should see:

✗ Policy check: DENIED
  Reason: budget_exceeded

The denial is still recorded as evidence — the policy engine caught it.

7. Inspect the audit trail​

List recent evidence and open one record:

talon audit list --limit 10
talon audit show <evidence-id>

Use the evidence ID from a previous run. You will see the full record: classification, PII flags, policy decision, and HMAC status.

What you've done​

You installed Talon, created a project, ran a governed agent, triggered a policy denial, and viewed the audit trail. Next you can: