AWS Strands
Add a safety layer to your AWS Strands agents. Every external action your agent takes is verified against your knowledge base and evaluated by your policies before it reaches the outside world.
How the integration works
- Install the
groundtruth-aipackage with the Strands extra. - Call create_tools() to get configured
@toolfunctions, then pass them to your agent. - Your agents call the tools before any external action. GroundTruth returns approved, blocked, or escalated.
Installation
pip install groundtruth-ai[strands]Set your API key as an environment variable:
export GROUNDTRUTH_API_KEY="hg_sk_your_api_key"Quick Start
from strands import Agent
from groundtruth.strands import create_tools
# Create all GroundTruth tools, configured with your settings
tools = create_tools(
agent_name="support-agent",
session_id="sess_123",
user_id="user_jane",
)
# Pass tools to your Strands agent
agent = Agent(tools=tools)
agent("Reply to the customer about our cancellation policy via email.")
create_tools() returns four @tool functions:
groundtruth_execute
Submit an action for safety verification. Returns approved, blocked, or escalated.
groundtruth_verify
Fact-check AI-generated text against your knowledge base.
groundtruth_await_approval
Poll for a human decision on an escalated action. Uses exponential backoff (2s → 30s) and connection reuse to handle long review times efficiently.
groundtruth_session_history
Retrieve past execution results for the current session.
Configuration
| Param | Description |
|---|---|
| api_key | API key. Falls back to GROUNDTRUTH_API_KEY env var. |
| agent_name | Identifies this agent in the execution log. |
| session_id | Session tracking ID for grouping executions. |
| user_id | Who the agent acts on behalf of. |
| base_url | Defaults to https://app.groundtruth.dev. |
The groundtruth_await_approval tool accepts additional params: timeout (default 3600s = 1 hour), poll_interval (default 2s, initial), max_poll_interval (default 30s, backoff cap). Polling uses exponential backoff and connection reuse to handle long human review times efficiently.
Customer Support Agent
A Strands agent that handles customer tickets with GroundTruth verification. The agent verifies its draft, sends it through the safety layer, and waits for approval if escalated.
from strands import Agent
from groundtruth.strands import create_tools
tools = create_tools(
agent_name="support-agent",
session_id="sess_support_001",
user_id="support-team",
)
agent = Agent(
system_prompt="""You are a customer support agent. When replying to customers:
1. Draft your reply
2. Use groundtruth_verify to check your draft for accuracy
3. Use groundtruth_execute with action='reply_ticket' to send it
4. If the action is ESCALATED, use groundtruth_await_approval to wait
5. If BLOCKED, use the suggested rewrite and resubmit""",
tools=tools,
)
agent("Reply to ticket #4521: customer asks about our cancellation policy.")
What happens at runtime
Scenario A: Reply is accurate
The agent drafts a correct reply. Verify returns risk 5%. Execute sends it. Approved — reply sent.
Scenario B: Reply has wrong info
The agent drafts incorrect info. Verify returns risk 72%. Policy triggers. Blocked — safe rewrite provided. The agent retries with the corrected text.
Scenario C: Mentions refunds
Content is accurate, but policy "Escalate refund mentions" triggers. Escalated — queued for human review. The agent calls groundtruth_await_approval and waits.
Using the Core Functions Directly
If you need programmatic access without the Strands @tool decorator, import the core functions directly:
from groundtruth import execute, verify
# Verify text
result = verify(answer="You can cancel anytime with a full refund.")
print(result)
# Execute an action
result = execute(
action="send_email",
params={"to": "customer@acme.com", "body": "..."},
content="Your email text here.",
channel="email",
agent="my-script",
)
print(result)