Skip to content

coding-agents.md

Latest commit

 

History

History
172 lines (127 loc) · 5.09 KB

coding-agents.md

File metadata and controls

172 lines (127 loc) · 5.09 KB

Coding Agents

Use this flow when Codex, Claude Code, Cursor, or another coding agent needs to wire AgentGuard into a repo without hidden network behavior or dashboard setup.

AgentGuard's job in this flow is narrow and deliberate: stop coding agents from looping, retrying forever, and burning budget. Keep the first integration local and auditable, then add the hosted dashboard later only if you need operational visibility.

Why this matters now

This repo stays anchored to coding agents because that is where enterprise AI pull is strongest right now.

Industry reporting continues to point to coding as one of the clearest early production use cases for AI. In an April 2026 report, a16z estimated that 29% of the Fortune 500 and about 19% of the Global 2000 were live paying customers of leading AI startups, with coding called out as the dominant use case by nearly an order of magnitude. They also cited repeated 10-20x productivity claims for AI coding tools. Source: AI Adoption by the Numbers.

That does not mean AgentGuard should widen into a generic AI SDK here. It means the coding-agent wedge is real:

  • more coding agents running in real repos
  • more retry loops, runaway tool calls, and unattended spend risk
  • more pressure to prove local safety before asking a team to adopt hosted ops

If you want ready-to-copy repo instructions for specific coding agents, start with coding-agent-safety-pack.md.

If you want AgentGuard to materialize those files for you:

agentguard skillpack --write

That writes .agentguard.json plus the instruction files into agentguard_skillpack/ so you can review the pack before applying it to a real repo.

Goal

Keep the first integration:

  • local-only
  • zero-dependency in the core SDK
  • deterministic
  • auditable from checked-in files

1. Check in repo-local defaults

Create .agentguard.json at the repo root:

{
  "profile": "coding-agent",
  "service": "support-agent",
  "trace_file": ".agentguard/traces.jsonl",
  "budget_usd": 5.0
}

What this does:

  • profile: "coding-agent" tightens the default LoopGuard and adds RetryGuard
  • .agentguard/traces.jsonl keeps local traces out of the project root
  • budget_usd gives the agent a safe default ceiling without dashboard coupling

What this does not do:

  • no API keys
  • no hosted control-plane settings
  • no secrets

If you want AgentGuard to generate this file together with coding-agent instructions:

agentguard skillpack --target codex --write
agentguard skillpack --target claude-code --write

2. Verify the local path

Run:

agentguard doctor

This:

  • makes no network calls
  • writes a small local trace
  • checks for optional integrations already installed
  • prints the smallest safe next-step snippet

3. Start from the raw starter

Run:

python examples/starters/agentguard_raw_quickstart.py
agentguard report .agentguard/traces.jsonl

That proves:

  • local trace writing works
  • the checked-in defaults are usable
  • the repo can run AgentGuard without provider credentials

4. Move to the real stack

Once the raw path works, either:

agentguard quickstart --framework openai
agentguard quickstart --framework langchain
agentguard quickstart --framework langgraph

or run the matching checked-in starter under examples/starters/.

If you want the SDK to create a starter file in-place for the repo or coding agent:

agentguard quickstart --framework raw --write
agentguard quickstart --framework openai --write --output agentguard_openai_quickstart.py

--write keeps the first-run flow local and auditable. It writes the exact starter shown by quickstart, then prints the next commands to run. It will not overwrite an existing file unless you add --force.

Those starter files live in the repo for onboarding and copy-paste setup. They are not part of the installed PyPI wheel.

5. Keep the boundary clean

For coding-agent onboarding, prefer:

import agentguard

agentguard.init(local_only=True)

That keeps the first run local even if an AGENTGUARD_API_KEY is present in the environment.

Use the dashboard later for:

  • retained history
  • team visibility
  • alerts
  • remote kill
  • governance

The SDK should prove local enforcement first. The dashboard remains the control plane.

If the coding agent already supports MCP, add @agentguard47/mcp-server only after the local SDK path is proven. That MCP bridge is for retained traces and alerts, not the first-run safety proof.

If your coding-agent runtime uses disposable workers or managed harnesses, generate a fresh session_id at runtime and pass it into agentguard.init() or Tracer(...) rather than checking it into .agentguard.json. That keeps shared session correlation dynamic while the repo-level defaults stay static. Guide: managed-agent-sessions.md

Once the repo-local path works, run the fuller walkthrough in coding-agent-smoke-test.md to step through the starter path, the offline demo, and the local budget-kill example.