Agent

The Agent class is the primary SDK interface for governed AI interactions.

Constructor

from tappass import Agent

agent = Agent(
    url="http://localhost:9620",     # TapPass server URL
    api_key="tp_...",                # agent API key
    model="gpt-4o-mini",            # default model
    flags={"pii": "mask"},          # default governance flags
    timeout=30,                     # request timeout (seconds)
    max_retries=2,                  # retry on transient errors
)

Chat

response = agent.chat("What are the GDPR requirements?")
print(response.content)                   # the answer
print(response.model)                     # "gpt-4o-mini"
print(response.pipeline.classification)   # "PUBLIC"
print(response.usage.total_tokens)        # 156

With per-call flags

response = agent.chat(
    "Send the report to the board",
    flags={"email": "block", "mode": "lockdown"},
)

With custom model

response = agent.chat("Complex analysis", model="gpt-4o")

Streaming

for chunk in agent.stream("Write a security policy"):
    print(chunk, end="", flush=True)

Async

response = await agent.achat("Analyze the data")

async for chunk in agent.astream("Summarize findings"):
    print(chunk, end="", flush=True)

Multi-turn conversations

agent.chat("My name is Alice")
response = agent.chat("What's my name?")
print(response.content)  # "Alice"
print(len(agent.history))  # 4 messages
agent.reset()  # clear history

Govern tools

tools = agent.govern([search, send_email, read_file])
# every call is now audited through TapPass

Sandbox

agent.secure()                    # default sandbox
agent.secure(tier="worker")       # progressive trust tier

Register programmatically

agent = Agent.register(
    "http://localhost:9620",
    agent_id="my-agent",
    framework="crewai",
    admin_key="tp_admin_...",
)
print(agent.api_key)  # save this. shown once

Resilience (fail-open / fail-closed)

Configure what happens when TapPass is unreachable:

from tappass.resilience import ResiliencePolicy, FailMode

agent = Agent(
    "http://localhost:9620",
    resilience=ResiliencePolicy(
        mode=FailMode.FAIL_OPEN_CACHED,  # or FAIL_CLOSED, FAIL_OPEN_LOGGED
        cache_ttl_seconds=300,
        max_offline_requests=100,
    ),
)

# Or via environment variable (no code change):
# export TAPPASS_FAIL_MODE=fail_open_cached

# Check resilience status
print(agent.resilience_status)

See the Resilience Guide for full details.

Context manager

with Agent("http://localhost:9620", "tp_...") as agent:
    response = agent.chat("Hello")