# Strands Agents

> Check every tool call a Strands agent makes with Thoth before the tool runs, in TypeScript or Python.

Source: https://docs.atensecurity.com/docs/sdks/strands

Thoth checks each tool call a [Strands Agents](https://strandsagents.com) agent
makes before the tool runs: your own tools, MCP tools, vended tools and agents
used as tools. It works with the TypeScript SDK (`@atensec/thoth` 0.2.0 or
later, tested with `@strands-agents/sdk` 1.23.0) and the Python SDK
(`atensec-thoth` 0.6.0 or later, tested with `strands-agents` 1.63.0). See
[framework compatibility](https://docs.atensecurity.com/docs/sdks/framework-compatibility).

## Connect

Register the agent in Thoth first, and give your app its connection settings:

```bash
export THOTH_AGENT_ID="support-agent"
export THOTH_TENANT_ID="your-tenant-id"
export THOTH_API_URL="https://api.atensecurity.com"  # trial and self-serve; Enterprise: your enforce. host
export THOTH_API_KEY="..."                           # a runtime key for this agent
```

[Your first governed agent](https://docs.atensecurity.com/docs/getting-started/quickstart) covers
registering an agent and creating its key.

## Govern the agent

**TypeScript**

```bash
npm install @atensec/thoth @strands-agents/sdk zod
```

Call `init()` once at startup. Every Strands tool in the process is then
checked before it runs, including tools created before `init()`. Run each
request inside `actingFor` for the user it serves:

```typescript title="agent.ts"
import { Agent, tool } from "@strands-agents/sdk";
import { z } from "zod";
import { actingFor, init } from "@atensec/thoth";

await init(); // reads THOTH_AGENT_ID, THOTH_TENANT_ID, THOTH_API_URL, THOTH_API_KEY

const lookupOrder = tool({
  name: "lookup_order",
  description: "Look up an order by ID",
  inputSchema: z.object({ orderId: z.string() }),
  callback: ({ orderId }) => orders.get(orderId),
});

const sendRefund = tool({
  name: "send_refund",
  description: "Refund an order",
  inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
  callback: ({ orderId, amount }) => payments.refund(orderId, amount),
});

const agent = new Agent({ tools: [lookupOrder, sendRefund] });

await actingFor("alice@example.com", () =>
  agent.invoke("Refund order A-1, it arrived damaged."),
);
```

`init()` patches the copy of Strands that Node resolves from
`@atensec/thoth`. If your app is bundled with its own copy (some Next.js and
edge builds), govern the tools directly instead:

```typescript
import { governStrandsTools } from "@atensec/thoth/strands";

const agent = new Agent({
  tools: governStrandsTools([lookupOrder, sendRefund], {
    agentId: "support-agent",
    tenantId: process.env.THOTH_TENANT_ID!,
    approvedScope: [],
    userId: "alice@example.com",
  }),
});
```

Thoth checks each call when the tool runs, with its final input, and the tool
runs with exactly the input Thoth checked, so a hook registered later can't
change it after the check.

**Python**

```bash
pip install atensec-thoth strands-agents
```

Call `thoth.init()` once at startup. Every Strands tool in the process is then
checked before it runs, including tools defined before `init()`. Run each
request inside `acting_for` for the user it serves:

```python title="agent.py"
from strands import Agent, tool

import thoth

thoth.init()  # reads THOTH_AGENT_ID, THOTH_TENANT_ID, THOTH_API_URL, THOTH_API_KEY


@tool
def lookup_order(order_id: str) -> str:
    """Look up an order by ID."""
    return orders.get(order_id)


@tool
def send_refund(order_id: str, amount: float) -> str:
    """Refund an order."""
    return payments.refund(order_id, amount)


agent = Agent(tools=[lookup_order, send_refund])

with thoth.acting_for("alice@example.com"):
    agent("Refund order A-1, it arrived damaged.")
```

Direct calls such as `agent.tool.send_refund(...)` and agents used as tools
(`agent.as_tool()`) are checked too.

## What each decision does

| Decision  | What happens                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALLOW`   | The tool runs.                                                                                                                                                                                          |
| `DENY`    | The tool never runs. Strands gets an error tool result saying Thoth refused the call, with the reason, and the agent carries on, so the model can tell the user.                                      |
| `STEP_UP` | The call waits for a person to approve it. If it's approved, the tool runs; otherwise it's refused as for `DENY`.                                                                                       |

If Thoth can't be reached, calls are refused unless you set fail-open
(`failOpen: true`, or `THOTH_FAIL_OPEN=true`).

The agent's observe or enforce mode is set in Thoth, not in code. Start a new
agent in [observe](https://docs.atensecurity.com/docs/operations/enforcement-modes): Thoth records what it
would have decided and every call runs. Switch the agent to enforce when the
observe summary shows it's ready.
