Skip to content

getting-started.md

Latest commit

 

History

History
316 lines (244 loc) · 8.08 KB

getting-started.md

File metadata and controls

316 lines (244 loc) · 8.08 KB

Getting Started

Choose your integration path. All paths share the same core kernel.

Path 1: HTTP Proxy (Zero Code Change)

Best for: any CLI, any language, any framework.

pip install agentassert-typec-proxy

Write a contract:

cat > contract.yaml << 'EOF'
dsl_version: "0.4"
contractspec: "1.0"
kind: agent
name: safety-minimal
description: "Block destructive tool calls only."
version: "0.1"
invariants:
  process:
    - tool_blocklist:
        tools: ["rm -rf /*", "curl|bash"]
        scope: session
recovery:
  on_hard_violation: raise
  on_soft_violation: log_and_continue
EOF

Start the proxy:

agentassert-proxy proxy start --contract contract.yaml --port 9000

Point your agent at it. The proxy acts as a drop-in replacement by intercepting provider HTTP requests. Configure your favorite tool as follows:

1. Claude Code

Point Claude Code to the proxy by setting the base URL in your terminal before launching:

export ANTHROPIC_BASE_URL=http://localhost:9000/anthropic
claude

Note: Every model call and tool execution made by Claude Code will now pass through the contract evaluation engine.

2. Antigravity IDE

Antigravity IDE targets both Gemini and DeepSeek (via OpenAI endpoint). Intercept both by exporting:

# Point OpenAI-compatible requests (like DeepSeek Pro) to proxy
export OPENAI_BASE_URL=http://localhost:9000/openai

# Point Gemini requests to proxy
export GEMINI_BASE_URL=http://localhost:9000/gemini

Ensure your terminal session or workspace runtime inherits these environment variables before starting the agent.

3. CommandCode

To govern CommandCode (cmd-mimo, cmd-ds), configure the environment variables globally:

export ANTHROPIC_BASE_URL=http://localhost:9000/anthropic
export OPENAI_BASE_URL=http://localhost:9000/openai
export GEMINI_BASE_URL=http://localhost:9000/gemini
export OPENROUTER_BASE_URL=http://localhost:9000/openrouter

Adding this to your shell profile (~/.zshrc or ~/.bash_profile) guarantees that CommandCode's local models and downstream APIs are intercepted.

4. Hermes CLI

To intercept Hermes CLI agent requests, update ~/.hermes/config.yaml to specify proxy upstream URLs:

# ~/.hermes/config.yaml
providers:
  openai:
    base_url: "http://127.0.0.1:9000/openai/v1"
  anthropic:
    base_url: "http://127.0.0.1:9000/anthropic/v1"
  gemini:
    base_url: "http://127.0.0.1:9000/gemini/v1"
  openrouter:
    base_url: "http://127.0.0.1:9000/openrouter/v1"

Or start the hermes command with env variables configured (export ANTHROPIC_BASE_URL=...).

5. Cursor

To route Cursor's AI queries through AgentAssert:

  • Terminal Launch: Set base URLs in terminal and start Cursor from there: 
    export ANTHROPIC_BASE_URL=http://localhost:9000/anthropic
export OPENAI_BASE_URL=http://localhost:9000/openai
cursor .
  • UI Configuration: Alternatively, go to Settings -> Models -> Custom API Keys / Base URLs and supply:
    • OpenAI: http://localhost:9000/openai/v1
    • Anthropic: http://localhost:9000/anthropic/v1

6. Windsurf

Cascade agent in Windsurf respects proxy configuration:

  • Terminal Launch: 
    export ANTHROPIC_BASE_URL=http://localhost:9000/anthropic
export OPENAI_BASE_URL=http://localhost:9000/openai
windsurf .
  • UI Settings: Go to Windsurf Settings -> AI Configurations -> Custom Endpoints:
    • OpenAI Compatible Base URL: http://localhost:9000/openai/v1
    • Anthropic Compatible Base URL: http://localhost:9000/anthropic/v1

7. OpenClaw

Edit your local openclaw_config.json to route through the proxy:

{
  "anthropic_base_url": "http://localhost:9000/anthropic/v1",
  "openai_base_url": "http://localhost:9000/openai/v1"
}

Or run the OpenClaw service inside a shell where the base URLs are exported.

8. Cline (VS Code Extension)

In the Cline panel:

  1. Click the Settings icon.
  2. Under API Provider, select OpenAI Compatible or Anthropic.
  3. Configure the Base URL:
    • OpenAI compatible: http://localhost:9000/openai/v1
    • Anthropic compatible: http://localhost:9000/anthropic/v1
  4. Enter any placeholder text for API Key (the proxy forwards the real ones automatically).

All provider API calls now flow through the contract layer. No code changes needed.

Full Proxy Guide →

Path 2: Python SDK (One-Line Wrap)

Best for: Python developers using Anthropic or OpenAI SDKs directly.

pip install agentassert-typec-sdk
from anthropic import Anthropic
from agentassert_typec_sdk import wrap

client = wrap(Anthropic(), "contract.yaml")

# Every call is now contract-enforced
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

Supported clients: anthropic.Anthropic, anthropic.AsyncAnthropic, openai.OpenAI, openai.AsyncOpenAI.

Full SDK Guide →

Path 3: Claude Code Hook (Zero Code Change)

Best for: Claude Code CLI power users.

pip install agentassert-typec-claude-code

Install the hook:

agentassert-claude-code install --contract safety-minimal.yaml

Check status:

agentassert-claude-code status

Remove the hook:

agentassert-claude-code uninstall

Three contract templates ship with the package: safety-minimal, partner-mode, full-governance.

Full Claude Code Guide →

Path 4: npm (Node.js Ecosystem)

npx agentassert-typec proxy start --contract contract.yaml --port 9000

Same as the HTTP proxy, zero-install via npm. Downloads the pre-built binary.

Path 5: Homebrew (macOS)

brew install agentassert-typec
agentassert-proxy proxy start --contract contract.yaml

Your First Contract

Here's a production-ready contract with all 7 operators:

dsl_version: "0.4"
contractspec: "1.0"
kind: agent
name: full-governance
description: "Full behavioral contract with all process operators."
version: "0.1"

invariants:
  process:
    # 1. Require challenge before recommendation
    - must_precede:
        before: "challenge"
        after: "recommendation"
        scope: turn

    # 2. State cost before paid API calls
    - must_state:
        field: "cost"
        before_tool_pattern: "tap_*|paid_api_*"
        rationale: "Per cost-control policy"

    # 3. Block destructive tools
    - tool_blocklist:
        tools:
          - "rm -rf /*"
          - "curl|bash"
          - "*--no-verify"
        scope: session

    # 4. Restrict tools for specific skills
    - tool_allowlist:
        tools: ["Read", "Write", "Edit", "Grep", "Glob"]
        scope: "skill:seo-content-optimizer"

    # 5. Cap token usage per turn
    - context_budget:
        max_tokens_per_turn: 60000
        action_on_breach: warn

    # 6. Detect behavioral drift
    - process_drift:
        window_size: 10
        jsd_threshold: 0.30
        action: log

    # 7. LLM-as-judge for qualitative rules
    - judge_predicate:
        rubric: "Response shows L99 conviction (no 'depends', no 'either works')"
        sample_rate: 0.20
        model: ds-flash-free
        action_on_fail: theta_penalty
        cost_ceiling_usd_per_session: 0.10

recovery:
  on_hard_violation: raise
  on_soft_violation: log_and_continue

satisfaction:
  p: 0.95
  delta: 0.10
  k: 3

Full DSL Reference →

Verifying It Works

After starting the proxy, test that blocked tools actually get blocked:

# This call should return a ContractBreachError
curl -X POST http://localhost:9000/anthropic/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Run: rm -rf /"}]
  }'

The proxy returns a 400 with the violation details instead of forwarding to Anthropic.

Next Steps