# SDK and API Reference
Source: https://docs.vaultak.com/api-reference

Complete Vaultak SDK and REST API documentation, v0.5.0

## Installation

```
pip install vaultak
```

## Initialization

```
from vaultak import Vaultak, ActionType, KillSwitchMode

vt = Vaultak(
    api_key="vtk_your_api_key_here",
    allowed_action_types=[ActionType.FILE_READ, ActionType.API_CALL],
    allowed_resources=["/tmp/*", "/data/readonly/*"],
    blocked_resources=["prod.*", "*.env"],
    max_actions_per_minute=20,
    max_risk_score=0.7,
    mode=KillSwitchMode.PAUSE
)
```

## Parameters

| Parameter                 | Type           | Default            | Description                             |
| ------------------------- | -------------- | ------------------ | --------------------------------------- |
| api\_key                  | str            | required           | Your Vaultak API key                    |
| mode                      | KillSwitchMode | ALERT              | Response mode when violation occurs     |
| allowed\_action\_types    | list           | None (all allowed) | Whitelist of permitted action types     |
| allowed\_resources        | list           | None (all allowed) | Glob patterns for permitted resources   |
| blocked\_resources        | list           | \[]                | Glob patterns for blocked resources     |
| max\_actions\_per\_minute | int            | 60                 | Rate limit for agent actions            |
| max\_risk\_score          | float          | 1.0                | Hard ceiling on risk score              |
| risk\_threshold           | float          | 0.7                | Score that triggers the response mode   |
| rollback\_limit           | int            | 5                  | Max actions to reverse in ROLLBACK mode |

## Action Types

| Value                       | Description             |
| --------------------------- | ----------------------- |
| ActionType.FILE\_READ       | Reading a file          |
| ActionType.FILE\_WRITE      | Writing to a file       |
| ActionType.FILE\_DELETE     | Deleting a file         |
| ActionType.API\_CALL        | External API request    |
| ActionType.DATABASE\_QUERY  | Reading from a database |
| ActionType.DATABASE\_WRITE  | Writing to a database   |
| ActionType.CODE\_EXECUTION  | Executing code          |
| ActionType.NETWORK\_REQUEST | Network communication   |

## Response Modes

```
KillSwitchMode.ALERT     # Log and notify only (default)
KillSwitchMode.PAUSE     # Halt agent, await approval
KillSwitchMode.ROLLBACK  # Reverse last N actions and pause
```

## vt.monitor()

Context manager that wraps your entire agent session.

```
with vt.monitor("my-agent"):
    pass
```

## vt.log\_action()

Explicitly log a single agent action.

```
vt.log_action(
    agent_id="my-agent",
    action_type="file_delete",
    resource="/data/sensitive.csv",
    payload={"reason": "cleanup"}
)
```

## 5-Dimensional Risk Scoring

Every action is scored across five dimensions:

| Dimension            | Description                                      |
| -------------------- | ------------------------------------------------ |
| Action severity      | How destructive is this action type?             |
| Resource sensitivity | How sensitive is the target resource?            |
| Payload anomaly      | Does the payload deviate from baseline?          |
| Frequency            | Is the agent acting unusually fast?              |
| Context              | Does this action fit the agent's normal pattern? |

## REST API

All endpoints require your API key in the header:

```
x-api-key: vtk_your_api_key_here
```

## POST /api/check

Pre-execution risk check. Returns decision before action runs.

```
curl -X POST https://vaultak.com/api/check
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{"agent_id": "my-agent", "action_type": "file_delete", "resource": "/data/sensitive.csv"}'
```

Response:

```
{
  "decision": "block",
  "reason": "Resource '/data/sensitive.csv' is blocked for this agent",
  "risk_score": 0.91,
  "risk_breakdown": {...}
}
```

## PATCH /api/agents//profile

Update an agent's permission profile from the API.

```
curl -X PATCH https://vaultak.com/api/agents/my-agent/profile
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{
    "allowed_action_types": ["file_read", "api_call"],
    "allowed_resources": ["/tmp/*"],
    "blocked_resources": ["prod.*", "*.env"],
    "max_actions_per_minute": 20,
    "max_risk_score": 0.7
  }'
```

## POST /api/actions

Log a completed agent action.

```
curl -X POST https://vaultak.com/api/actions
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{"agent_id": "my-agent", "action_type": "file_write", "resource": "/tmp/output.txt"}'
```

## GET /api/agents

List all registered agents with their permission profiles.

```
curl https://vaultak.com/api/agents
  -H "x-api-key: vtk_your_api_key_here"
```

## GET /api/alerts

Retrieve active alerts.

```
curl https://vaultak.com/api/alerts
  -H "x-api-key: vtk_your_api_key_here"
```

## Security Policies

Policies let you define rules that automatically block, pause, or allow actions.

```
curl -X POST https://vaultak.com/api/policies
  -H "x-api-key: vtk_your_api_key_here"
  -H "Content-Type: application/json"
  -d '{
    "name": "no-prod-deletes",
    "action_type": "file_delete",
    "resource_pattern": "prod.*",
    "effect": "block",
    "max_risk_score": 0.5,
    "priority": 10
  }'
```

| Field             | Type  | Description                              |
| ----------------- | ----- | ---------------------------------------- |
| name              | str   | Human-readable policy name               |
| action\_type      | str   | Action type to match                     |
| resource\_pattern | str   | Glob pattern for resource matching       |
| effect            | str   | block, pause, or allow                   |
| max\_risk\_score  | float | Trigger if risk score exceeds this value |
| priority          | int   | Higher priority policies evaluated first |


# Welcome to Vaultak
Source: https://docs.vaultak.com/index

Runtime security for autonomous AI agents

## What is Vaultak?

Vaultak is a runtime security platform for autonomous AI agents. It intercepts every action your agents take, scores risk in real time across five behavioral dimensions, enforces declarative policies, and automatically alerts, pauses, or rolls back agents that exceed your configured thresholds.

## Two ways to deploy

### Vaultak Core

For developers who want deep programmatic integration. Add five lines of code to your agent and get full behavioral monitoring, risk scoring, policy enforcement, and automatic rollback.

\`\`\`bash
pip install vaultak
\`\`\`

### Vaultak Sentry

A desktop application for macOS, Windows, and Linux. Download it, connect your API key, and any agent running on the machine is immediately monitored, zero code changes required.

[Download Vaultak Sentry →](https://vaultak.com/download)

Both products use the same API key and the same dashboard at [app.vaultak.com](https://app.vaultak.com).

## What Vaultak provides

* **Behavioral risk scoring**, every action scored 0-100 across five dimensions
* **Threshold-based response**, configure Alert, Pause, and Rollback thresholds independently
* **Automatic rollback**, reverses agent state using stored snapshots
* **Policy engine**, declare exactly what each agent is authorized to do
* **Pre-execution enforcement**, actions are blocked before they run, not just logged after
* **PII masking**, automatically detects and masks PII in all logged events
* **SIEM integration**, forwards events to Splunk, Datadog, Sentinel, Slack, and PagerDuty
* **Red team simulation**, simulates 22 adversarial attack vectors before deployment
* **Shadow AI detection**, detects data flowing to unsanctioned AI services
* **MCP gateway security**, monitors and enforces policies on MCP connections
* **On-premises deployment**, full Docker Compose package for air-gapped environments
* **HIPAA, SOC 2, GDPR, and PCI-DSS ready**, immutable audit trail for compliance

## Get Started

<CardGroup>
  <Card title="Quickstart: Core SDK" icon="code" href="/quickstart">
    Add five lines of code to your agent
  </Card>

  <Card title="Quickstart: Sentry" icon="shield" href="/sentry">
    Zero-code desktop app for instant monitoring
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Full REST API documentation
  </Card>

  <Card title="Dashboard" icon="chart-bar" href="https://app.vaultak.com">
    View your agents in real time
  </Card>
</CardGroup>


# Agency Swarm
Source: https://docs.vaultak.com/integrations/agency-swarm

Risk-score every tool call and agent message, enforce policy rules, and mask PII in Agency Swarm agencies.

[Agency Swarm](https://github.com/VRSEN/agency-swarm) is a multi-agent orchestration framework built around role-based agents and tool-calling. Vaultak plugs into two integration points it exposes natively.

<CardGroup>
  <Card title="Input & Output Guardrails" icon="shield-halved" href="#guardrail-approach">
    Risk-score incoming messages and mask PII in agent responses using Agency Swarm's native guardrail decorators.
  </Card>

  <Card title="BaseTool Mixin" icon="wrench" href="#tool-level-approach">
    Intercept individual tool calls before they execute by mixing Vaultak checks into any BaseTool subclass.
  </Card>
</CardGroup>

## Install

```bash theme={null}
pip install vaultak agency-swarm
```

Sign up at [vaultak.com](https://vaultak.com) to get your API key (starts with `vtk_`).

## Guardrail Approach

Agency Swarm's `@input_guardrail` and `@output_guardrail` decorators let you intercept messages at the agency boundary without touching any tool code.

* **Input guardrail** — risk-scores each incoming message before the agent processes it; blocks if the score meets or exceeds your threshold.
* **Output guardrail** — masks PII in agent responses before they reach the user.

```python theme={null}
import asyncio
import os

from agency_swarm import (
    Agent,
    Agency,
    GuardrailFunctionOutput,
    RunContextWrapper,
    input_guardrail,
    output_guardrail,
)
from vaultak import Vaultak

vt = Vaultak(api_key=os.environ["VAULTAK_API_KEY"], agent_name="agency-swarm-agent")
RISK_THRESHOLD = 7.0


@input_guardrail
async def vaultak_input_guard(
    context: RunContextWrapper,
    agent: Agent,
    user_input: str | list[str],
) -> GuardrailFunctionOutput:
    text = user_input if isinstance(user_input, str) else " ".join(user_input)
    result = await asyncio.to_thread(vt.score_action, action="user-message", context={"input": text})
    if result.score >= RISK_THRESHOLD:
        return GuardrailFunctionOutput(
            output_info=f"[Vaultak] Blocked — risk score {result.score:.1f}/10. Review at app.vaultak.com",
            tripwire_triggered=True,
        )
    await asyncio.to_thread(vt.check_policy, tool_name="user-message", input_data=text)
    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)


@output_guardrail
async def vaultak_output_guard(
    context: RunContextWrapper,
    agent: Agent,
    response_text: str,
) -> GuardrailFunctionOutput:
    if isinstance(response_text, str):
        masked = await asyncio.to_thread(vt.mask_pii, response_text)
        if masked != response_text:
            return GuardrailFunctionOutput(output_info=masked, tripwire_triggered=True)
    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)


ceo = Agent(
    name="CEO",
    instructions="You orchestrate the agency and answer user questions.",
    input_guardrails=[vaultak_input_guard],
    output_guardrails=[vaultak_output_guard],
)

agency = Agency(agents=[ceo])
```

<Note>
  `asyncio.to_thread()` is required because Vaultak SDK calls are synchronous and guardrail functions are `async`. This keeps the event loop non-blocking.
</Note>

## Tool-Level Approach

For per-tool risk scoring, subclass `BaseTool` through the `VaultakMixin`. The mixin intercepts `run()`, calls Vaultak before execution, and masks PII in string outputs afterward.

```python theme={null}
import os
from typing import Any

from agency_swarm.tools import BaseTool
from pydantic import Field
from vaultak import Vaultak

vt = Vaultak(api_key=os.environ["VAULTAK_API_KEY"], agent_name="agency-swarm-agent")
RISK_THRESHOLD = 7.0


class VaultakMixin:
    def run(self) -> Any:
        tool_name = self.__class__.__name__
        args = self.model_dump()  # type: ignore[attr-defined]

        result = vt.score_action(action=tool_name, context=args)
        if result.score >= RISK_THRESHOLD:
            raise RuntimeError(
                f"[Vaultak] '{tool_name}' blocked — risk score {result.score:.1f}/10. "
                "Review at app.vaultak.com"
            )

        vt.check_policy(tool_name=tool_name, input_data=str(args))

        output = super().run()  # type: ignore[misc]
        return vt.mask_pii(output) if isinstance(output, str) else output


class LookupCustomer(VaultakMixin, BaseTool):
    """Look up a customer record by ID."""

    customer_id: str = Field(..., description="The customer ID to look up.")

    def run(self) -> str:
        return f"Customer {self.customer_id}: Alice Smith, alice@example.com"
```

<Note>
  Inherit `VaultakMixin` **before** `BaseTool` so Python's MRO calls `VaultakMixin.run()` first, then chains to your tool's `run()` via `super()`.
</Note>

## Combined Example

Use both approaches together for defence-in-depth: guardrails screen all messages, the mixin secures individual high-risk tools.

```python theme={null}
import asyncio
import os

from agency_swarm import Agent, Agency, GuardrailFunctionOutput, RunContextWrapper, input_guardrail
from agency_swarm.tools import BaseTool
from pydantic import Field
from vaultak import Vaultak

vt = Vaultak(api_key=os.environ["VAULTAK_API_KEY"], agent_name="agency-swarm-agent")
RISK_THRESHOLD = 7.0


@input_guardrail
async def vaultak_input_guard(
    context: RunContextWrapper, agent: Agent, user_input: str | list[str]
) -> GuardrailFunctionOutput:
    text = user_input if isinstance(user_input, str) else " ".join(user_input)
    result = await asyncio.to_thread(vt.score_action, action="user-message", context={"input": text})
    if result.score >= RISK_THRESHOLD:
        return GuardrailFunctionOutput(
            output_info=f"[Vaultak] Blocked — risk score {result.score:.1f}/10. Review at app.vaultak.com",
            tripwire_triggered=True,
        )
    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)


class VaultakMixin:
    def run(self):
        tool_name = self.__class__.__name__
        args = self.model_dump()
        result = vt.score_action(action=tool_name, context=args)
        if result.score >= RISK_THRESHOLD:
            raise RuntimeError(
                f"[Vaultak] '{tool_name}' blocked — risk score {result.score:.1f}/10. "
                "Review at app.vaultak.com"
            )
        vt.check_policy(tool_name=tool_name, input_data=str(args))
        output = super().run()
        return vt.mask_pii(output) if isinstance(output, str) else output


class SendEmail(VaultakMixin, BaseTool):
    """Send an email to a recipient."""

    to: str = Field(..., description="Recipient email address.")
    subject: str = Field(..., description="Email subject.")
    body: str = Field(..., description="Email body.")

    def run(self) -> str:
        return f"Email sent to {self.to} — subject: '{self.subject}'"


ceo = Agent(
    name="CEO",
    instructions="You are an executive assistant. Use SendEmail for outbound communication.",
    tools=[SendEmail],
    input_guardrails=[vaultak_input_guard],
)

agency = Agency(agents=[ceo])
```

## Stricter thresholds for sensitive agencies

For agencies with access to databases, payment systems, or external APIs, lower the threshold to block medium-risk actions:

```python theme={null}
RISK_THRESHOLD = 5.0  # Block anything scoring above medium risk
```

## Configuration reference

| Parameter        | Type    | Default                | Description                                        |
| ---------------- | ------- | ---------------------- | -------------------------------------------------- |
| `api_key`        | `str`   | —                      | Your Vaultak API key — required                    |
| `agent_name`     | `str`   | `"agency-swarm-agent"` | Label shown in the Vaultak dashboard               |
| `RISK_THRESHOLD` | `float` | `7.0`                  | Score (0-10) at or above which actions are blocked |

## What gets monitored

| Event                              | Vaultak action                                                           |
| ---------------------------------- | ------------------------------------------------------------------------ |
| Incoming message (input guardrail) | Risk-scored; blocked via `tripwire_triggered=True` if score >= threshold |
| Policy check                       | Validated against your dashboard-configured rules                        |
| Tool call (`VaultakMixin`)         | Risk-scored; blocked via `RuntimeError` if score >= threshold            |
| Tool output (`VaultakMixin`)       | Scanned for PII and masked before returning to the agent                 |
| Agent response (output guardrail)  | PII masked before the response reaches the user                          |

## Links

* [Agency Swarm on GitHub](https://github.com/VRSEN/agency-swarm)
* [Vaultak dashboard](https://app.vaultak.com)
* [Vaultak API reference](/api-reference)


# Quickstart - Vaultak Core
Source: https://docs.vaultak.com/quickstart

Add runtime security to your AI agent in 5 minutes

## Step 1: Install

\`\`\`bash
pip install vaultak
\`\`\`

## Step 2: Get your API key

Sign up at [app.vaultak.com](https://app.vaultak.com). Your API key is on the API Key tab. It starts with `vtk_`.

## Step 3: Wrap your agent

\`\`\`python
from vaultak import Vaultak

vt = Vaultak(api\_key="vtk\_your\_api\_key\_here")

with vt.monitor("my-agent"):
agent.run()
\`\`\`

Every action your agent takes is now monitored, risk-scored, and logged in real time.

**Node.js:**

```javascript theme={null}
const { Vaultak } = require("vaultak");

const vt = new Vaultak({ apiKey: "vtk_your_api_key_here" });
vt.monitor("my-agent");

myAgent.run();
```

## Step 4: Configure thresholds

\`\`\`python
vt = Vaultak(
api\_key="vtk\_your\_api\_key\_here",
alert\_threshold=30,    # Score >= 30: alert and log
pause\_threshold=60,    # Score >= 60: halt agent, await review
rollback\_threshold=85  # Score >= 85: auto-rollback and halt
)
\`\`\`

## Step 5: Define what your agent is allowed to do

\`\`\`python
vt = Vaultak(
api\_key="vtk\_your\_api\_key\_here",
allowed\_resources=\["/tmp/*", "/data/readonly/*"],
blocked\_resources=\["prod.*", "*.env", "\*.key"],
max\_actions\_per\_minute=20,
)
\`\`\`

Policies can also be created and managed in the dashboard, no code changes needed.

## Response modes

| Mode         | Trigger     | Behavior                                        |
| ------------ | ----------- | ----------------------------------------------- |
| **Alert**    | Score >= 30 | Logs event, sends notification, agent continues |
| **Pause**    | Score >= 60 | Halts agent, queues action for human review     |
| **Rollback** | Score >= 85 | Reverses state using snapshot, halts agent      |

## Works with any framework

\`\`\`python

# LangChain

with vt.monitor("langchain-agent"):
response = llm.invoke(prompt)

# CrewAI

with vt.monitor("crew-agent"):
crew\.kickoff()

# AutoGen

with vt.monitor("autogen-agent"):
agent.run()
\`\`\`

## Environment variable

\`\`\`bash
export VAULTAK\_API\_KEY=vtk\_your\_api\_key\_here
\`\`\`

\`\`\`python
vt = Vaultak()  # Reads from VAULTAK\_API\_KEY automatically
\`\`\`

## Next steps

* [View your agents in the dashboard](https://app.vaultak.com)
* [Read the full API reference](/api-reference)
* [Learn about Vaultak Sentry for zero-code deployment](/sentry)


# Quickstart - Vaultak Sentry
Source: https://docs.vaultak.com/sentry

Monitor any AI agent with zero code changes using the Vaultak Sentry desktop app

Vaultak Sentry is a desktop application for macOS, Windows, and Linux that monitors any AI agent running on your machine without requiring any changes to the agent code. Install it in two minutes and get full behavioral monitoring immediately.

## Download

Download the installer for your platform from [vaultak.com/download](https://vaultak.com/download):

| Platform              | File                               |
| --------------------- | ---------------------------------- |
| macOS (Apple Silicon) | `VaultakSentry-1.0.0-arm64.pkg`    |
| Windows               | `VaultakSentry-1.0.0-windows.zip`  |
| Linux                 | `VaultakSentry-1.0.0-linux.tar.gz` |

## Installation

### macOS

1. Download `VaultakSentry-1.0.0-arm64.pkg`
2. **Right-click** the file and select **Open**
3. Click **Open** in the security dialog
4. Follow the installer prompts

### Windows

1. Download `VaultakSentry-1.0.0-windows.zip`
2. Extract the zip file
3. Run `VaultakSentry.exe`
4. If SmartScreen appears, click **More info** then **Run anyway**

### Linux

\`\`\`bash
tar -xzf VaultakSentry-1.0.0-linux.tar.gz
cd VaultakSentry-1.0.0
./VaultakSentry
\`\`\`

## Connect to your account

1. Open the Vaultak Sentry app
2. Enter your API key from [app.vaultak.com](https://app.vaultak.com)
3. Click **Connect**
4. The status indicator turns green, monitoring has begun

## Run your agent through Sentry

Instead of running your agent directly:

```bash theme={null}
python my_agent.py
```

Run it through Sentry:

```bash theme={null}
vaultak-sentry run python my_agent.py
```

That is the only change. Works with any language:

```bash theme={null}
# Python
vaultak-sentry run --name my-agent python my_agent.py

# Node.js
vaultak-sentry run --name my-agent node my_agent.js

# Any executable
vaultak-sentry run --name my-agent ./my_agent
```

With custom thresholds:

```bash theme={null}
vaultak-sentry run --name my-agent --alert-threshold 30 --pause-threshold 60 --rollback-threshold 85 python my_agent.py
```

Block specific resources:

```bash theme={null}
vaultak-sentry run --name my-agent --block "*.env" "prod.*" python my_agent.py
```

## Configure thresholds

| Threshold    | Default | Behavior                           |
| ------------ | ------- | ---------------------------------- |
| **Alert**    | 30      | Log event and send notification    |
| **Pause**    | 60      | Halt agent, queue for human review |
| **Rollback** | 85      | Auto-reverse state, halt agent     |

Thresholds can be adjusted at any time without restarting the app.

## What Sentry monitors

* **Network connections**, every outbound API call and external service connection
* **File system**, reads, writes, and deletes by agent processes
* **LLM API calls**, requests to OpenAI, Anthropic, and other providers
* **Process activity**, subprocesses spawned by agents

## Privacy

Sentry monitors that actions occur, it does not read file contents or environment variable values. Data sent to Vaultak servers: action type, resource path or hostname, timestamp, and risk score only.

## Frequently asked questions

**Do I need to modify my agent code?**
No. Sentry monitors at the network and OS level.

**Will Sentry slow down my agent?**
No. Sentry runs as a separate background process and does not intercept or delay agent actions.

**I see a security warning on macOS. Is this normal?**
Yes. Right-click the installer and select Open to bypass the Gatekeeper warning. This is standard for apps not yet signed with an Apple Developer certificate.

**Can I use Sentry and Core together?**
Yes. Events from both products appear in the same dashboard.

## Next steps

* [View your agents in the dashboard](https://app.vaultak.com)
* [Learn about the Core SDK for programmatic integration](/quickstart)
* [Read the full API reference](/api-reference)