Your agent and harness, defined in code.
Write the agent, the workflow around it, and the scorers that grade it, in Python, TypeScript, or Go. Queues, retries, checkpoints, and timers come with the runtime, so the code you write is only your logic.
Read the build docsfrom agnt5 import Agent, Context, tool
@tool
async def lookup_order(ctx: Context, order_id: str) -> dict:
"""Get an order's items, total, delivery date, and final_sale flag."""
return await orders.get(order_id) # your order API
@tool
async def search_policy(ctx: Context, question: str) -> str:
"""Search the refund and returns policy."""
return await policy_docs.search(question) # your docs index
support_agent = Agent(
name="support_agent",
model="anthropic/claude-sonnet-5-5",
instructions="""You resolve refund requests for Acme.
Look up the order first. Offer a refund only when the
policy allows it, and quote the policy when you do.""",
tools=[lookup_order, search_policy],
max_iterations=8,
)from agnt5 import WorkflowContext, workflow
from support.agent import support_agent
from support.steps import issue_refund, send_follow_up
@workflow
async def handle_refund(ctx: WorkflowContext, order_id: str, message: str) -> dict:
# the agent's model and tool calls are recorded as it works
answer = await support_agent.run(f"Order {order_id}: {message}", context=ctx)
# parks the run until someone answers, for minutes or days
decision = await ctx.wait_for_user(
question=f"Refund order {order_id}?\n\n{answer.output}",
input_type="approval",
options=[{"id": "approve", "label": "Approve"},
{"id": "reject", "label": "Reject"}],
)
if decision == "reject":
return {"status": "declined"}
await ctx.step(issue_refund, order_id)
await ctx.sleep(3 * 24 * 60 * 60, name="wait_3_days") # survives restarts
await ctx.step(send_follow_up, order_id)
return {"status": "refunded"}from agnt5 import StepContext, step
@step(retries=3, backoff="exponential")
async def issue_refund(ctx: StepContext, order_id: str) -> str:
# a flaky payment API: failed calls retry with backoff, and the
# idempotency key stops a retry from refunding twice
key = ctx.activation.idempotency_key
return await payments.refund(order_id, idempotency_key=key)
@step(retries=5)
async def send_follow_up(ctx: StepContext, order_id: str) -> None:
refund = await payments.get_refund(order_id)
await mailer.send(order_id, f"Your refund of {refund.amount} has posted.")from agnt5 import ScorerContext, ScorerRequest, ScorerResult, scorer
@scorer(name="quotes_policy", description="A refund recommendation quotes the policy")
async def quotes_policy(ctx: ScorerContext, request: ScorerRequest) -> ScorerResult:
quoted = "§" in str(request.output)
return ScorerResult(
score=1.0 if quoted else 0.0,
passed=quoted,
explanation="Quotes the policy" if quoted else "No policy section quoted",
)
# follows_refund_policy is the built-in llm_judge scorer: no code,
# just the refund policy as its criteriaimport asyncio
from agnt5 import Worker
from support.agent import lookup_order, search_policy, support_agent
from support.scorers import quotes_policy
from support.workflow import handle_refund
async def main() -> None:
worker = Worker(
service_name="support-desk",
agents=[support_agent],
tools=[lookup_order, search_policy],
workflows=[handle_refund], # its steps run inside it
scorers=[quotes_policy],
)
await worker.run() # takes runs off the AGNT5 queue
asyncio.run(main())import { Agent, LM, tool } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';
export const lookupOrder = tool('lookup_order', {
description: "Get an order's items, total, delivery date, and final_sale flag.",
inputSchema: { type: 'object', properties: { orderId: { type: 'string' } } },
}, async (ctx: Context, args: { orderId: string }) => orders.get(args.orderId));
export const searchPolicy = tool('search_policy', {
description: 'Search the refund and returns policy.',
inputSchema: { type: 'object', properties: { question: { type: 'string' } } },
}, async (ctx: Context, args: { question: string }) => policyDocs.search(args.question));
export const supportAgent = new Agent({
name: 'support_agent',
model: LM.anthropic(),
modelName: 'anthropic/claude-sonnet-5-5',
instructions: `You resolve refund requests for Acme.
Look up the order first. Offer a refund only when the
policy allows it, and quote the policy when you do.`,
tools: [lookupOrder, searchPolicy],
maxIterations: 8,
});import { workflow } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';
import { supportAgent } from './agent';
import { issueRefund, sendFollowUp } from './steps';
export const handleRefund = workflow('handle_refund',
async (ctx: Context, input: { orderId: string; message: string }) => {
// the agent's model and tool calls are recorded as it works
const answer = await supportAgent.run(`Order ${input.orderId}: ${input.message}`, ctx);
// parks the run until someone answers, for minutes or days
const decision = await ctx.waitForUser(`Refund order ${input.orderId}?\n\n${answer.output}`, {
inputType: 'approval',
options: [{ id: 'approve', label: 'Approve' },
{ id: 'reject', label: 'Reject' }],
});
if (decision === 'reject') return { status: 'declined' };
const order = { input: { orderId: input.orderId } };
await ctx.step(issueRefund, order);
await ctx.sleep(3 * 24 * 60 * 60 * 1000, 'wait_3_days'); // survives restarts
await ctx.step(sendFollowUp, order);
return { status: 'refunded' };
});import { step } from '@agnt5/sdk';
// a flaky payment API: failed calls retry with backoff, and the
// idempotency key stops a retry from refunding twice
export const issueRefund = step('issue_refund',
async (ctx, { orderId }: { orderId: string }) =>
payments.refund(orderId, { idempotencyKey: ctx.activation.idempotencyKey }),
{ retries: { maxAttempts: 3 }, backoff: { type: 'exponential' } });
export const sendFollowUp = step('send_follow_up',
async (ctx, { orderId }: { orderId: string }) => {
const refund = await payments.getRefund(orderId);
await mailer.send(orderId, `Your refund of ${refund.amount} has posted.`);
},
{ retries: { maxAttempts: 5 } });import { scorer, ScorerResult } from '@agnt5/sdk';
export const quotesPolicy = scorer('quotes_policy', 'A refund recommendation quotes the policy')(
async (ctx, request) => {
const quoted = String(request.output).includes('§');
return new ScorerResult({ score: quoted ? 1 : 0, passed: quoted });
},
);
// follows_refund_policy is the built-in llm_judge scorer: no code,
// just the refund policy as its criteriaimport { Worker } from '@agnt5/sdk';
import { supportAgent } from './src/agent';
import './src/workflow'; // the workflow and the tools register on import
import './src/scorers'; // and so does the scorer
const worker = new Worker('support-desk', { serviceVersion: '1.0.0' });
worker.registerAgents([supportAgent]);
await worker.run(); // takes runs off the AGNT5 queuepackage support
import (
"context"
"os"
"github.com/agnt5dev/sdk-go/agnt5"
)
const instructions = `You resolve refund requests for Acme.
Look up the order first. Offer a refund only when the
policy allows it, and quote the policy when you do.`
var SupportAgent *agnt5.Agent
var Tools []agnt5.Tool
func lookupOrder(_ context.Context, args map[string]any) (any, error) {
id, _ := args["order_id"].(string)
return orders.Get(id) // your order API
}
func NewSupportAgent() error {
lookup, err := agnt5.NewTool("lookup_order", lookupOrder,
agnt5.WithToolDescription("Get an order's items, total, delivery date, and final_sale flag."),
agnt5.WithToolSchema(schema("order_id")))
if err != nil {
return err
}
policy, err := agnt5.NewTool("search_policy", searchPolicy, // searchPolicy and schema() live alongside
agnt5.WithToolDescription("Search the refund and returns policy."),
agnt5.WithToolSchema(schema("question")))
if err != nil {
return err
}
Tools = []agnt5.Tool{lookup, policy}
SupportAgent, err = agnt5.NewAgent("support_agent",
agnt5.WithAgentModel(agnt5.NewAnthropicModel(agnt5.AnthropicConfig{
APIKey: os.Getenv("ANTHROPIC_API_KEY"),
Model: "claude-sonnet-5-5",
})),
agnt5.WithAgentInstructions(instructions),
agnt5.WithAgentTools(Tools...),
agnt5.WithAgentMaxTurns(8),
)
return err
}package support
import (
"context"
"time"
"github.com/agnt5dev/sdk-go/agnt5"
)
type Ticket struct {
OrderID string `json:"order_id"`
Message string `json:"message"`
}
func HandleRefund(ctx *agnt5.Context, t Ticket) (string, error) {
// the agent's model and tool calls are recorded as it works
answer, err := agnt5.Step(ctx, "support_agent", func(context.Context) (agnt5.AgentResult, error) {
return SupportAgent.Run(ctx, agnt5.AgentInput{Message: "Order " + t.OrderID + ": " + t.Message})
})
if err != nil {
return "", err
}
// parks the run until someone answers, for minutes or days
approved, err := ctx.RequestApproval("Refund order "+t.OrderID+"?\n\n"+answer.Response, nil)
if err != nil || !approved {
return "declined", err
}
if _, err := IssueRefund.Execute(ctx, t.OrderID, "issue_refund"); err != nil {
return "", err
}
if err := ctx.Sleep(72*time.Hour, agnt5.WithSleepKey("wait_3_days")); err != nil {
return "", err // the timer survives restarts
}
_, err = SendFollowUp.Execute(ctx, t.OrderID, "send_follow_up")
return "refunded", err
}package support
import (
"time"
"github.com/agnt5dev/sdk-go/agnt5"
)
// a flaky payment API: failed calls retry with backoff, and the
// idempotency key stops a retry from refunding twice
var IssueRefund = must(agnt5.NewStep("issue_refund",
func(ctx *agnt5.Context, orderID string) (string, error) {
act, _ := agnt5.ActivationFromContext(ctx)
return payments.Refund(orderID, act.IdempotencyKey)
},
agnt5.StepConfig{MaxAttempts: 3, InitialInterval: time.Second}))
var SendFollowUp = must(agnt5.NewStep("send_follow_up",
func(ctx *agnt5.Context, orderID string) (string, error) {
return "", mailer.SendRefundPosted(orderID)
},
agnt5.StepConfig{MaxAttempts: 5}))
func must[T any](v T, err error) T {
if err != nil {
panic(err)
}
return v
}package support
import (
"context"
"fmt"
"strings"
"github.com/agnt5dev/sdk-go/agnt5"
)
var QuotesPolicy = agnt5.ScorerConfig{
Name: "quotes_policy",
Description: "A refund recommendation quotes the policy",
Handler: func(_ context.Context, req agnt5.ScorerRequest) (agnt5.ScorerResult, error) {
quoted := strings.Contains(fmt.Sprint(req.Output), "§")
score := 0.0
if quoted {
score = 1.0
}
return agnt5.ScorerResult{Score: score, Passed: quoted}, nil
},
}
// follows_refund_policy is the built-in llm_judge scorer: no code,
// just the refund policy as its criteriapackage main
import (
"context"
"log"
"github.com/agnt5dev/sdk-go/agnt5"
"support-desk/src/support"
)
func main() {
worker := agnt5.NewWorker("support-desk")
check(support.NewSupportAgent())
// Go registers each part; the workflow's steps run inside it
for _, tool := range support.Tools {
check(agnt5.RegisterTool(worker, tool))
}
check(agnt5.RegisterAgent(worker, support.SupportAgent))
check(agnt5.RegisterWorkflow(worker, "handle_refund", support.HandleRefund))
check(agnt5.RegisterScorer(worker, support.QuotesPolicy))
// takes runs off the AGNT5 queue
check(worker.Run(context.Background()))
}
func check(err error) {
if err != nil {
log.Fatal(err)
}
}Production, without the platform work.
One command puts support-desk behind an authenticated API, with environments, autoscaling workers, and state kept per customer. You don’t stand any of it up.
Read the run docs$ agnt5 deploy --env production ok Bundle (1.4s) ok Deployment created (2.7s) Replicas active, switching traffic to this deployment... ok Ready (49.3s) - 2/2 replica(s) active, production routes to this deployment $ agnt5 deployment checks --env production
| After 1 hour | Deploy 14 | Deploy 15 | |
|---|---|---|---|
| Run failure rate | 0.4% | 0.4% | no change |
| New error signatures | none | none | no change |
| Latency p50 | 6.1s | 6.0s | no change |
| Cost per run | $0.021 | $0.021 | no change |
The checks run again at 15 minutes and 24 hours.
Preview
deploy 16
From agnt5 deploy. Stops after an hour.
Staging
deploy 15
Checked and ready.
Production
deploy 14
Serving traffic.
Promoting points production at the same image staging ran: nothing is rebuilt. Rolling back points it at the deploy before.
| Secret | Preview | Staging | Production |
|---|---|---|---|
| ANTHROPIC_API_KEY | set | set | set |
| PAYMENTS_API_KEY | test key | test key | live key |
$ curl -X POST https://gw.agnt5.com/v1/workflows/handle_refund/run \ -H "X-API-KEY: $AGNT5_KEY" \ -d '{"order_id": "A-1042", "message": "My blender arrived cracked."}' → run 7f3a started
| Service key | Scopes | Environment | |
|---|---|---|---|
| production-runner | run, workflow | production | |
| ci-runner | run | staging |
429Over the key’s limit: Too Many Requests, with Retry-After: 12
$ agnt5 deploy --env production --min-replicas 2 --max-replicas 6Dashed lines: the minimum and the maximum. A run on a worker that is resized or replaced goes back on the queue and runs again.
| Customer | Memory scope | Sessions |
|---|---|---|
| Acme | user:acme-41 | 3 |
| Globex | user:globex-07 | 1 |
| Initech | user:initech-12 | 5 |
Pass your customer’s id with each run. The agent’s memory and conversations are kept under that customer, and each session keeps its own history.
Limits per customerbeta
Cap each customer at 10 concurrent runs and 60 runs a minute, keyed by customer id, so one busy customer can’t starve the rest.
See every run and make it better.
Every run is traced and measured from its first deploy. Run evals with your scorers on real production runs, and ship the change that tests better.
Read the improve docs- Input
- {"order_id": "A-1042", "message": "My blender arrived cracked."}
- Output
- {"status": "refunded"}
- Deployment
- deploy 14 · production
- Model
- anthropic/claude-sonnet-5-5
- Loop
- 2 model calls, 2 tool calls
- Tokens
- 3,184 in · 412 out · $0.016
- Answer
- Damaged on arrival, 6 days after delivery: §2 allows a full refund. Recommend $84.00.
- Tokens
- 1,412 in · 58 out
- Asked for
- lookup_order, then search_policy
- Input
- {"order_id": "A-1042"}
- Output
- {"item": "Blender", "total": 84.00, "final_sale": false}
- Input
- {"question": "damaged on arrival"}
- Output
- "§2 Damaged items: full refund within 30 days of delivery."
- Tokens
- 1,772 in · 354 out
- Wrote
- the recommendation: refund $84.00 under §2
- Question
- Refund order A-1042? Recommend $84.00 (§2, damaged on arrival).
- Answer
- approve, from dana@acme.com in Studio
- Waited
- 1h 11m (drawn shorter here)
- Attempts
- 2: the first failed, the second went through
- Retries
- up to 3 attempts, exponential backoff
- Result
- "re_3PqX9a"
- Error
- 503 Service Unavailable from the payments API
- Then
- retried after 2s
- Result
- refund re_3PqX9a created
- Idempotency key
- the same on both attempts, so the refund happened once
- Timer
- 3 days, then the follow-up
- Survives
- worker restarts while it counts down
- Result
- emailed the customer: refund of $84.00 has posted
12,480Runs
98.6%Succeeded
7.9sp95 latency
$214.30LLM cost
LLM usage by model
| Top errors | Component | Runs |
|---|---|---|
| 503 from the payments API, retried | issue_refund | 41 |
| Tool timeout | search_policy | 6 |
Filter by deployment, component, or status. Every number comes from the same traces.
follows_refund_policy0 / 23 to 22 / 23
quotes_policy21 / 23 to 23 / 23
cost per run$0.021 to $0.022
| Run | Deploy 14 | Your change |
|---|---|---|
| 51d0 | refund $129.00 | store credit, final sale |
| a9c4 | refund $74.00 | store credit, final sale |
| 0b7d | refund $95.00 | partial refund $40.00 |
$ agnt5 experiments run ex_8f21 --deployment-id "$CANDIDATE" --wait --fail-on-gate RUN STATUS PASSED PASS_RATE THRESHOLD PROGRESS FAILED 9c41e2b0.. completed true 95.7% 90.0% 23/23 1
Online evals keep scoring a sample of live runs after you ship, and alert when the pass rate drops.
support_agent recommends refunds on final-sale orders
What failedIn 23 runs, the agent recommended a refund for an order that lookup_order returned with final_sale: true.
Likely causeThe agent’s instructions don’t mention final-sale orders. agent.py:19agent.ts:18agent.go:10
Fix promptIn src/support/agent.py, add to support_agent’s instructions that orders with final_sale set aren’t refundable, and to offer store credit. Then test it on the 23 runs in issue #12.In src/agent.ts, add to support_agent’s instructions that orders with final_sale set aren’t refundable, and to offer store credit. Then test it on the 23 runs in issue #12.In src/support/agent.go, add to support_agent’s instructions that orders with final_sale set aren’t refundable, and to offer store credit. Then test it on the 23 runs in issue #12.
Runsrun 51d0run a9c4run 77e2+ 20 more
Bring the agents you already have.
No rewrite. Wrap your agent’s entry point in an AGNT5 function and call your framework exactly as you do today. Your prompts, tools, and model providers stay as they are.
Step 1
Install the CLI
curl -LsSf https://agnt5.com/cli.sh | bashFor Python, TypeScript, or Go projects.
Step 2
Wrap your existing agent
@function # on your entry pointOne decorator. The agent code inside it doesn’t change.
Step 3
Deploy
agnt5 deployYour first run is recorded, start to finish.
Works with
OpenAI Agents SDKClaude Agent SDKGoogle ADKVercel AI SDKCloudflare WorkersDeploy your first agent in 5 minutes.
Start free with 250K steps a month.