v1.0.3

Observe Agent Runtime

This tutorial connects an externally run agent to AI Governance Control Plane without moving the agent, its prompts, or its private output into the control plane.

What you will complete

You will record one small agent run: start it, add one safe operational event, mark it complete, and find the resulting timeline in Studio. The example uses a claims agent, but the same pattern works for any framework or in-house runtime.

Your agent runtime → start record → safe event → completed record → Studio timeline

Before you start

Start the local stack from an AI Governance Control Plane checkout and sign in to Studio. You also need an access token permitted to create runtime evidence in your chosen organization and project.

bash

./servers.sh

Set the values used by the commands below:

bash

export AI_GOVERNANCE_API_URL=http://localhost:8000
export AI_GOVERNANCE_TOKEN=replace-with-a-bearer-token
export AI_GOVERNANCE_ORGANIZATION_ID=org_default
export AI_GOVERNANCE_PROJECT_ID=project_default

Use your own runtime in production

This is an integration pattern, not an instruction to run agents in the control plane. Send these requests from your runtime or its connector after it has performed the real work.

1. Start Execution

When the agent starts a new run, create an execution record. Keep theexternal_execution_id stable for delivery retries: sending the same start record again is safe and returns the existing execution.

bash

curl --request POST "$AI_GOVERNANCE_API_URL/api/v1/agent-executions" \
  --header "Authorization: Bearer $AI_GOVERNANCE_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "X-AI-Governance-Organization-Id: $AI_GOVERNANCE_ORGANIZATION_ID" \
  --header "X-AI-Governance-Project-Id: $AI_GOVERNANCE_PROJECT_ID" \
  --data '{
    "agent_id": "claims-agent-v2",
    "agent_name": "Claims Processing Agent",
    "agent_version": "2.1.0",
    "external_execution_id": "claim-8421-review-001",
    "runtime_provider": "your-runtime",
    "correlation_id": "claim-8421",
    "metadata": {"workflow": "claims_intake"}
  }'

Copy the returned execution.execution_id and use it in the next two steps. It is the control-plane identifier for this one run.

2. Add safe event

As the run progresses, send ordered facts that help someone understand the operation. Here, the agent completed a policy lookup in 120 milliseconds. The idempotency key makes retrying this event delivery safe.

bash

export EXECUTION_ID=replace-with-execution.execution_id

curl --request POST "$AI_GOVERNANCE_API_URL/api/v1/agent-executions/$EXECUTION_ID/events" \
  --header "Authorization: Bearer $AI_GOVERNANCE_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "X-AI-Governance-Organization-Id: $AI_GOVERNANCE_ORGANIZATION_ID" \
  --header "X-AI-Governance-Project-Id: $AI_GOVERNANCE_PROJECT_ID" \
  --data '{
    "event_type": "TOOL_CALL",
    "actor_id": "policy.lookup",
    "actor_type": "TOOL",
    "idempotency_key": "claim-8421-review-001-policy-lookup",
    "attributes": {"tool": "policy.lookup", "latency_ms": 120, "status": "SUCCEEDED"},
    "evidence_references": ["artifact://claims/8421/policy-summary"]
  }'

Do not send a transcript

Event attributes must not contain prompts, model responses, messages, hidden reasoning, credentials, tool arguments, tool outputs, or tool results. Use an approved evidence reference when another authorized system needs the details.

3. Complete Execution

Mark the run terminal when your agent finishes. A completed historical execution is evidence: it cannot later be changed into a different terminal status.

bash

curl --request POST "$AI_GOVERNANCE_API_URL/api/v1/agent-executions/$EXECUTION_ID/complete" \
  --header "Authorization: Bearer $AI_GOVERNANCE_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "X-AI-Governance-Organization-Id: $AI_GOVERNANCE_ORGANIZATION_ID" \
  --header "X-AI-Governance-Project-Id: $AI_GOVERNANCE_PROJECT_ID" \
  --data '{"status":"SUCCEEDED"}'

4. Review

Open Agents Runtime in Studio.

Confirm that the organization and project selectors match the values used above.
Choose Claims Processing Agent from the observed-agent list.
Open the new execution and check its status

Open the new execution and check its status, duration, event count, and event timeline.

A successful submission means the record is available for review. It does not mean the control plane has evaluated the quality of the agent's decision. Findings appear only when configured detectors have enough evidence to identify a measurable condition.

What to do next

Read the Agents Runtime reference for the concepts and boundaries. When your runtime can safely publish structured tool evidence and perform isolated replays, continue to Run Causal Audit.