智能代理控制

Verify your setup works

After installing a project connector, walk the current shipped path in that project:

1. Ask the agent to read project context. Routed reads such as list_workspace, read_file, get_file_info, and instruction_surface_status should allow. 2. Ask the agent to create or edit a file, for example:

Create avp-test.txt with the text hello

The configured connector should stop the native mutation with redirect guidance; the agent should then use the controlled MCP route, where risky writes require approval. 3. Open the approval page when prompted and review the bounded proof details. 4. Inspect local proof from the CLI:

agentveil-mcp-proxy events show --last

The default human output should include lines like decision=approval_required and tool=write_file without dumping raw JSON. Use --json when you need structured fields.

Quick Start

Use AgentVeil with a supported project connector, or run the Core MCP Proxy directly.

Example Risk Patterns

AgentVeil is useful when an agent crosses from reading context into changing state.

Gemini CLI project connector

pip install agentveil-mcp-proxy
agentveil-mcp-proxy setup gemini-cli --choose-folder --yes

Choose the project folder you want to protect, then open / restart Gemini CLI for that project. Gemini CLI asks you to trust the project folder before it loads local settings, hooks, and MCP servers.

After setup and folder trust, in the configured project:

• supported native Gemini CLI mutation tools are checked by a project-local hook;
• risky native mutations are blocked with redirect guidance toward the controlled MCP route;
• AgentVeil MCP writes go through the proxy approval path;
• bounded evidence is written locally.

Hermes CLI controlled MCP profile

Hermes CLI is launched through AgentVeil rather than installed as a persistent project hook:

pip install agentveil-mcp-proxy
agentveil-mcp-proxy launch --profile hermes-cli --choose-folder -- \
  hermes chat -q "Create a project note"

The launcher configures a project-local Hermes home, routes Hermes to the AgentVeil MCP tools, and keeps local proof/evidence in the selected project.

In this profile:

- Hermes project work is routed through the AgentVeil MCP route; - routed reads, writes, approval, sandbox boundaries, redirect guidance, and local proof use the shared AgentVeil control layer; - native Hermes tools are limited by profile settings, but AgentVeil does not claim host-wide control of Hermes or the machine.

Python SDK and advanced protocol primitives

Advanced Python SDK package: agentveil.

The public SDK also includes protocol primitives that can support custom integrations: local did:key identity, delegation receipts, credential helpers, reputation credential access, receipt helpers, and optional framework adapter modules under agentveil.tools.* when their framework dependencies are installed.

These primitives are not the main product path in this README. For direct use, start with:

• Agent Network (Advanced)
• DelegationReceipt Guide
• Proof Packet Guide

Agentic media / broadcast workflows

Agentic media and broadcast workflows often start with read access to files, assets, CMS entries, Git history, or SQL query results, then cross into higher-risk writes and sends: publishing updates, changing a repository, mutating a database, or sending final content.

This is one example of the broader risk pattern:

agent reads metadata        -> allow / observe
agent edits file or record  -> approval required
agent publishes or sends    -> approval / redirect
agent tries unsafe mutation -> block
agent action completes      -> bounded evidence

AgentVeil does not ship native broadcast, CMS, or SQL integrations in this package. The example describes the risk pattern for agentic workflows.

Comparison