Your first governed agent

Start with two local callbacks: one returns a greeting, the other must never execute. You do not need a model API key or an existing agent framework. After this guide, you will have checked an action before execution and verified the result in your tenant's decision history.

1. Set your connection details

In a local terminal, set these variables using your trial details. Load the key from your secret manager or a private file; do not commit it or paste it into shared terminal logs.

export THOTH_TENANT_ID="<your-trial-tenant-id>"
export THOTH_API_URL="<your-unified-tenant-api-base-url>"
export THOTH_API_KEY="$(cat /absolute/private/path/trial-execute-key)"
export THOTH_FAIL_OPEN=false

2. Install the SDK and run your agent

Use Python 3.12+, Node.js 22+, or Go 1.25+. These examples need no model API key and make no external tool calls. They use the same trial-demo agent and tool names as the onboarding demo. Start with demo.read; only proceed to shell.exec after the read succeeds.

The trial demo policy is expected to allow demo.read and block shell.exec. approved_scope describes the agent's intended tools; it does not install or override server policy. The shell.exec callback is a guard that raises an error if reached; it never starts a shell.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install atensec-thoth==0.5.23

import os
from thoth import instrument, ThothPolicyViolation
 
 
class Tool:
    def __init__(self, name, fn):
        self.name = name
        self.run = fn
 
 
def forbidden_shell():
    raise RuntimeError("Unexpected execution: inspect the trial demo policy")
 
 
class Agent:
    def __init__(self):
        self.tools = [
            Tool("demo.read", lambda: "Hello from the trial demo"),
            Tool("shell.exec", forbidden_shell),
        ]
 
 
agent = instrument(
    Agent(),
    agent_id="trial-demo",
    tenant_id=os.environ["THOTH_TENANT_ID"],
    api_url=os.environ["THOTH_API_URL"],
    api_key=os.environ["THOTH_API_KEY"],
    approved_scope=["demo.read"],
    user_id="trial-developer",
    environment="prod",
    enforcement="progressive",
)
 
# Any failure here stops the demo before the denied tool is attempted.
print(agent.tools[0].run())
try:
    agent.tools[1].run()
except ThothPolicyViolation as refusal:
    print(f"Tool refused: {refusal}")
else:
    raise RuntimeError("Expected shell.exec to be refused")

3. Verify the result

With the configured demo policy, the terminal prints:

Hello from the trial demo
Tool refused: ...shell.exec...demo policy...

The refusal's exact wording varies by SDK and policy. Treat a missing greeting, an unexpected execution error, or a different decision as a failed check.

Confirm the demo.read decision is ALLOW and the shell.exec decision is BLOCK in decision history, including the reason and correlation ID. A refusal exception alone is insufficient: fail-closed SDKs also refuse calls on authentication, rate-limit, or transport failures. Resolve those errors before counting the demo as successful. A STEP_UP pauses for approval; it is not the expected result for this two-tool demo.

The demo BLOCK quarantines trial-demo. An administrator must open Agents → trial-demo → Restore Agent before repeating the examples, including switching SDK languages. Then start with demo.read again.

Onboarding activation progress records the first authenticated, finalized enforcement decision. It can record a refused action too. Check decision history separately to verify the expected policy outcome and available evidence; the progress indicator does not prove tool execution or a finalized evidence export.

4. Connect your own agent

You have verified a permitted action and a refusal. Next, instrument your own agent and keep its tool execution behind the same policy check. If the demo did not behave as expected, use the troubleshooting guide before continuing.