> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/agent-integration.md).

# Agent Integration

Warrant has two integration sides:

1. the **agent side** submits structured proposals and obeys verdicts; and
2. the **deployment side** registers actuators that own provider credentials and side effects.

Keeping those sides separate is the security boundary. An agent must not submit a proposal, receive `allow`, and then call the provider itself.

### Agent-side contract

Every mutating tool should resolve to one call:

```http
POST /v1/actions
Authorization: Bearer <tenant-agent-key>
Content-Type: application/json
```

Then follow this decision table:

| Result            | Agent behavior                                                 |
| ----------------- | -------------------------------------------------------------- |
| `allow`           | Return the Warrant record. Warrant owns execution.             |
| `needs_approval`  | Stop the tool turn and surface the action id and review route. |
| `deny`            | Stop and surface the blocking reasons.                         |
| HTTP `202`        | Poll `polling_url`; never duplicate the provider call.         |
| `outcome_unknown` | Escalate for operator reconciliation.                          |

### Python client

```python
from warrant.client import WarrantClient

warrant = WarrantClient.from_env()
verdict = warrant.submit_action(proposal)

match verdict["decision"]:
    case "allow":
        return verdict
    case "needs_approval":
        return {
            "status": "held",
            "action_id": verdict["proposal_id"],
            "review_route": verdict["review_route"],
        }
    case "deny":
        return {"status": "denied", "reasons": verdict["blocking_reasons"]}
```

`WarrantClient` is deliberately thin: it wraps HTTP and error handling but does not embed the gate or actuator into the agent process.

### JavaScript or TypeScript

No SDK is required:

```ts
const response = await fetch(`${process.env.WARRANT_URL}/v1/actions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WARRANT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(proposal),
});

const verdict = await response.json();
if (!response.ok && response.status !== 202) throw new Error(verdict.detail);
if (verdict.decision !== "allow") return verdict;
return verdict; // the provider call does not happen here
```

### LangChain tool boundary

Wrap a mutating tool so it creates a proposal and returns only Warrant's response:

```python
from langchain_core.tools import tool

@tool
def restart_service(service: str, environment: str) -> dict:
    return warrant.submit_action({
        "proposal_id": f"restart:{environment}:{service}",
        "actor": {"agent_id": "langchain-worker"},
        "summary": f"Restart {service} in {environment}",
        "action": {
            "target_system": "kubernetes",
            "operation": "restart_service",
            "parameters": {"service": service, "environment": environment},
            "rollback_plan": "restart the previous service revision",
        },
        "risk": {"level": "medium", "blast_radius": f"{environment} {service}"},
    })
```

The provider credential belongs to Warrant's actuator deployment, not the LangChain worker.

### MCP or custom runners

An MCP server exposed to the agent can be a small Warrant client:

```sh
hermes mcp add warrant \
  --command python \
  --env WARRANT_URL=https://warrant.example.com WARRANT_API_KEY=<tenant-agent-key> \
  --args tools/warrant_mcp_server.py
```

Expose only proposal-backed tools. A `needs_approval` or `deny` response is terminal for that tool call.

For the provider-facing MCP boundary, continue with Production actuators.

### Deployment-side actuator

Provider adapters, registry wiring, credential custody, and idempotency are documented separately on Production actuators.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/agent-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.