AI Access and Tool Contracts
English | 中文
Status: direction + contract doc. AgentProvenance should be callable BY agents, not just observed by humans. The asset is the capability surface (already
daemon /v1REST + CLI--json); MCP, OpenAPI, provider tool-schemas, SDK wrappers, and the CLI are all thin ADAPTERS over the same contract. Define the contract once (this doc), generate the adapters.
Reference: OpenAPI · AI/MCP tools · Python integration.
0. The trust boundary (load-bearing, applies to every adapter)
- An agent MAY query everything (read tools) and MAY assert its own app-side context (bind a ToolCallScope, record a tool call).
- An agent MUST NOT be able to fabricate system-side events or signatures. System evidence and off-host signing stay outside the agent's control, or the tamper-evidence thesis breaks.
- Verdicts (the inline gate) are computed by the trusted policy/correlation engine, never by the calling model.
The integration order is read tools, app-context writes, then policy preflight. Read-only tools still require appropriate access to the underlying evidence.
1. The capability contract (read surface)
Every operation already exists as a daemon endpoint and a CLI command, each returning a versioned JSON envelope. This is the underlying read surface; the current MCP and provider catalogs expose a subset, listed in section 2.1.
| Operation | Daemon endpoint | CLI | Schema |
|---|---|---|---|
| verify_run | GET /v1/graph/verify?run= | graph verify --run --json | agentprovenance.verify/v1 |
| get_signals | GET /v1/signals?run= | signals list --run --json | agentprovenance.signals/v1 |
| explain | GET /v1/graph/explain?{event,process,tool-call,file,risk,artifact}= | graph explain --json | agentprovenance.explain/v1 |
| get_timeline | GET /v1/timeline?run= | timeline --run --json | agentprovenance.timeline/v1 |
| observe_summary | GET /v1/observe/summary?run= | observe summary --json | agentprovenance.observability_summary/v1 |
| list_risks | GET /v1/security/risks?run= | security risks --run --json | agentprovenance.security_risks/v1 |
| list_responses | GET /v1/security/responses?run= | security responses --run --json | agentprovenance.security_responses/v1 |
| list_deviations | GET /v1/security/deviations?run= | security deviations --run --json | agentprovenance.security_deviations/v1 |
| list_events | GET /v1/telemetry/events?run= (paged) | telemetry list --run --json | agentprovenance.telemetry_events/v1 |
| list_windows | GET /v1/telemetry/windows?run= | telemetry windows --run --json | agentprovenance.telemetry_event_windows/v1 |
| explain_correlations | GET /v1/telemetry/correlations?run= | telemetry correlations --run --json | agentprovenance.telemetry_correlations/v1 |
| get_audit_associations | GET /v1/telemetry/audit-associations?run= | telemetry audit-associations --run --json | agentprovenance.audit_associations/v1 |
| health | GET /v1/health | (daemon) | agentprovenance.daemon_health/v1 |
Context-write surface (phase 2, shipped as AI tools): bind_scope (register a
ToolCallScope binding, over correlation.RecordBinding) and record_tool_call
(anchor an app-asserted tool call). Both write only app-side context — forced
binding_source=ai_asserted / status=asserted, no execution, no system events —
so they cannot fabricate independent (kernel_correlated) evidence. The daemon
analogues remain POST /v1/telemetry/bind and POST /v1/record (the latter also
executes; the AI tool deliberately does not). Gate (phase 3, shipped):
evaluate_action.
2. Adapters (one contract, many surfaces)
| Adapter | What it is | Effort | Audience |
|---|---|---|---|
| CLI-as-tool | a stable --json contract + a tool manual prompt |
~0 (exists) | code-execution agents (Claude Code, etc.) |
| OpenAPI spec | one openapi.yaml over the read endpoints | low | GPT Actions, any OpenAPI tool importer |
| Provider tool-schemas | Anthropic tool-use / OpenAI function defs + dispatcher | low-med | direct tool-calling apps |
| MCP server | stdio MCP server wrapping the read surface + gate (agentprov ai mcp) — shipped |
med | MCP clients |
| SDK framework tools | LangChain/LlamaIndex/CrewAI/Agents-SDK wrappers over the Python SDK | med | agents built in those frameworks |
| A2A agent-card | expose AgentProvenance as a delegatable agent | med (frontier) | agent-to-agent delegation |
2.1 MCP server (agentprov ai mcp)
A stdio MCP server (spec revision 2025-06-18, JSON-RPC 2.0 over stdin/stdout)
generated from the same internal/aitools.Catalog() / Dispatch as the provider
tool-schemas and ai call — so MCP clients see exactly the nine tools (six read,
the evaluate_action gate, and the bind_scope / record_tool_call context-write
tools) with no separate contract to drift. The two write tools carry
annotations.readOnlyHint=false; everything else is hinted read-only. Only
JSON-RPC is written to stdout; diagnostics stay on stderr. Tool results carry the
serialized JSON in a text content block, with object results also surfaced as
structuredContent. Wire it into a client, e.g.:
{ "mcpServers": { "agentprovenance": { "command": "agentprov", "args": ["ai", "mcp"] } } }
initialize → tools/list → tools/call is the full handshake; the trust
boundary in §0 is inherited unchanged (no fabrication of system events/signatures;
the gate verdict is the engine's, not the model's). Implementation:
internal/mcpserver.
3. Policy preflight
A harness can call evaluate_action before attempting a command, connection, or
file operation. The current implementation evaluates caller-supplied
event_type, command/args, dst_ip, and path with the local default policy
engine. It returns allow, deny, quarantine, or kill, a rule identifier,
and a reason.
This call does not execute or block the action, persist a policy decision, or query runtime evidence to establish what happened. The caller must honor the result. The inputs describe a proposed action, so a successful preflight is not proof that the later action matched it or was observed by the sensor. Correlated post-execution evidence remains a separate query path.
4. Roadmap
- Read adapters (done): CLI tool manual + OpenAPI spec, provider tool-schemas, and the stdio MCP server (§2.1) -- all over section 1.
- Context-write tools (done): bind_scope / record_tool_call so an agent registers its own ToolCallScope (zero-instrumentation correlation), within the trust boundary — app-asserted only, never forging system evidence.
- Policy preflight (done): evaluate_action over the default policy engine; enforcement remains the caller's responsibility.
- Analysis direction (optional): an observer-LLM step over the SIGNED graph (semantic risk explanation on tamper-evident evidence).