Your agent, defined in code.
Write agents, tools, and workflows in Python, TypeScript, or Go. The highlighted calls are AGNT5; everything else is your own code.
Read the build docsfrom agnt5 import WorkflowContext, workflow
from support.agents import support_agent
from support.functions import issue_refund
@workflow
async def handle_refund(ctx: WorkflowContext, order_id: str, message: str) -> dict:
# every model and tool call is recorded in the run's trace
answer = await support_agent.run(f"Order {order_id}: {message}", context=ctx)
# pauses here for hours or days, until someone answers
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"}
# checkpointed: once it succeeds, it never runs again
await ctx.step(issue_refund, order_id)
return {"status": "refunded"}from agnt5 import Agent
from support.tools import lookup_order, search_policy
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 Context, tool
@tool
async def lookup_order(ctx: Context, order_id: str) -> dict:
"""Get an order's items, total, and shipping status.
Args:
order_id: The order number, like A-1042.
"""
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 indexfrom agnt5 import FunctionContext, function
@function(retries=3, backoff="exponential")
async def issue_refund(ctx: FunctionContext, order_id: str) -> dict:
"""Refund an order through the payment API."""
if ctx.attempt > 0:
ctx.logger.info("Retrying refund", order_id=order_id, attempt=ctx.attempt)
return await payments.refund(order_id) # a flaky payment APIimport asyncio
from agnt5 import Worker
from support.agents import support_agent
from support.functions import issue_refund
from support.tools import lookup_order, search_policy
from support.workflows import handle_refund
async def main() -> None:
worker = Worker(
service_name="support-desk",
agents=[support_agent],
tools=[lookup_order, search_policy],
functions=[issue_refund],
workflows=[handle_refund],
)
await worker.run() # connects to AGNT5 and waits for runs
asyncio.run(main())# agnt5 dev runs the worker on your machine;
# agnt5 deploy --env preview ships it.
name: support-desk
language: python
language_version: ">=3.11"
environment: dev
worker:
command: "uv run python app.py"import { workflow } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';
import { supportAgent } from './agents';
import { issueRefund } from './functions';
export const handleRefund = workflow('handle_refund',
async (ctx: Context, input: { orderId: string; message: string }) => {
// every model and tool call is recorded in the run's trace
const answer = await supportAgent.run(`Order ${input.orderId}: ${input.message}`, ctx);
// pauses here for hours or days, until someone answers
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' };
// checkpointed: once it succeeds, it never runs again
await ctx.step('issue_refund', () => issueRefund(ctx, { orderId: input.orderId }));
return { status: 'refunded' };
});import { Agent, LM } from '@agnt5/sdk';
import { lookupOrder, searchPolicy } from './tools';
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 { tool } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';
export const lookupOrder = tool('lookup_order', {
description: "Get an order's items, total, and shipping status.",
inputSchema: {
type: 'object',
properties: { orderId: { type: 'string', description: 'Like A-1042' } },
required: ['orderId'],
},
}, async (ctx: Context, args: { orderId: string }) => {
return orders.get(args.orderId); // your order API
});
export const searchPolicy = tool('search_policy', {
description: 'Search the refund and returns policy.',
inputSchema: {
type: 'object',
properties: { question: { type: 'string' } },
required: ['question'],
},
}, async (ctx: Context, args: { question: string }) => {
return policyDocs.search(args.question); // your docs index
});import { fn } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';
export const issueRefund = fn('issue_refund')
.retry({ maxAttempts: 3 })
.backoff({ type: 'exponential' })
.run(async (ctx: Context, input: { orderId: string }) => {
if (ctx.attempt > 0) {
ctx.logger.info('Retrying refund', { orderId: input.orderId, attempt: ctx.attempt });
}
return payments.refund(input.orderId); // a flaky payment API
});import { Worker } from '@agnt5/sdk';
import { supportAgent } from './src/agents';
import './src/workflows'; // tools, functions, and workflows register on import
const worker = new Worker('support-desk', { serviceVersion: '1.0.0' });
worker.registerAgents([supportAgent]);
await worker.run(); // connects to AGNT5 and waits for runs# agnt5 dev runs the worker on your machine;
# agnt5 deploy --env preview ships it.
name: support-desk
language: typescript
language_version: ">=22"
environment: dev
worker:
command: "npx tsx app.ts"package support
import (
"context"
"github.com/agnt5dev/sdk-go/agnt5"
)
func HandleRefund(ctx *agnt5.Context, t Ticket) (string, error) {
// every model and tool call is recorded in the run's trace
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
}
// pauses here for hours or days, until someone answers
approved, err := ctx.RequestApproval("Refund order "+t.OrderID+"?\n\n"+answer.Response, nil)
if err != nil || !approved {
return "declined", err
}
// checkpointed: once it succeeds, it never runs again
return agnt5.Step(ctx, "issue_refund", func(context.Context) (string, error) {
return IssueRefund(ctx, t)
})
}package support
import (
"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
func NewSupportAgent(tools ...agnt5.Tool) (err error) {
model := agnt5.NewAnthropicModel(agnt5.AnthropicConfig{
APIKey: os.Getenv("ANTHROPIC_API_KEY"),
Model: "claude-sonnet-5-5",
})
SupportAgent, err = agnt5.NewAgent("support_agent",
agnt5.WithAgentModel(model),
agnt5.WithAgentInstructions(instructions),
agnt5.WithAgentTools(tools...),
agnt5.WithAgentMaxTurns(8),
)
return err
}package support
import (
"context"
"github.com/agnt5dev/sdk-go/agnt5"
)
func NewLookupOrder() (agnt5.Tool, error) {
return agnt5.NewTool("lookup_order",
func(_ context.Context, args map[string]any) (any, error) {
orderID, _ := args["order_id"].(string)
return orders.Get(orderID) // your order API
},
agnt5.WithToolDescription("Get an order's items, total, and shipping status."),
agnt5.WithToolSchema(map[string]any{
"type": "object",
"properties": map[string]any{
"order_id": map[string]any{"type": "string", "description": "Like A-1042"},
},
"required": []string{"order_id"},
}),
)
}
// NewSearchPolicy is built the same way.package support
import "github.com/agnt5dev/sdk-go/agnt5"
type Ticket struct {
OrderID string `json:"order_id"`
Message string `json:"message"`
}
// IssueRefund calls a flaky payment API. main.go registers it
// with a retry policy, so failed calls retry with backoff.
func IssueRefund(ctx *agnt5.Context, t Ticket) (string, error) {
if ctx.Attempt() > 0 {
ctx.Logger().Info("Retrying refund", "order_id", t.OrderID, "attempt", ctx.Attempt())
}
return payments.Refund(t.OrderID) // your payment API
}package main
import (
"context"
"log"
"github.com/agnt5dev/sdk-go/agnt5"
"support-desk/src/support"
)
func main() {
worker := agnt5.NewWorker("support-desk")
lookup, err := support.NewLookupOrder()
must(err)
policy, err := support.NewSearchPolicy()
must(err)
must(support.NewSupportAgent(lookup, policy))
must(agnt5.RegisterTool(worker, lookup))
must(agnt5.RegisterTool(worker, policy))
must(agnt5.RegisterAgent(worker, support.SupportAgent))
must(agnt5.RegisterFunction(worker, "issue_refund", support.IssueRefund,
agnt5.WithRetry(3, 250, 5000),
agnt5.WithBackoff("exponential", 2),
))
must(agnt5.RegisterWorkflow(worker, "handle_refund", support.HandleRefund))
// connects to AGNT5 and waits for runs
must(worker.Run(context.Background()))
}
func must(err error) {
if err != nil {
log.Fatal(err)
}
}# agnt5 dev runs the worker on your machine;
# agnt5 deploy --env preview ships it.
name: support-desk
language: go
language_version: "1.26"
environment: dev
worker:
command: "go run ."Run it, and watch every step.
Deploy support-desk with agnt5 deploy, and every call to handle_refund becomes a run you can open: each model call, tool call, retry, and approval, as it happens.
Read the run docs- Input
- {"order_id": "A-1042", "message": "My blender arrived cracked."}
- Output
- {"status": "refunded"}
- Deployment
- deploy 14 · production
- Started by
- agnt5 run handle_refund --env 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", "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
- Damaged on arrival, 6 days after delivery: §2 allows a full refund. Recommend $84.00.
- Question
- Refund order A-1042? Recommend $84.00 (§2, damaged on arrival).
- Answer
- approve
- Answered by
- 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
- Ran
- once: a later restart returns this saved result
- Input
- {"order_id": "A-2210", "message": "My kettle stopped working after 3 weeks."}
- Status
- paused at the approval step
- 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
- Faulty after 3 weeks: §3 allows a refund. Recommend $45.00.
- Tokens
- 1,412 in · 58 out
- Asked for
- lookup_order, then search_policy
- Input
- {"order_id": "A-2210"}
- Output
- {"item": "Kettle", "final_sale": false, …}
- Input
- {"question": "stopped working"}
- Output
- "§3 Faulty items: refund within 30 days of delivery."
- Tokens
- 1,772 in · 354 out
- Wrote
- Faulty after 3 weeks: §3 allows a refund. Recommend $45.00.
- Question
- Refund order A-2210? Recommend $45.00 (§3, faulty within 30 days).
- Status
- paused: the run carries on from here when someone answers
- Answer in
- Studio, or POST /v1/workflows/resume/2c91
- If the worker restarts
- the run stays paused
- Input
- {"order_id": "A-1187", "message": "Wrong size. It's unopened."}
- Output
- {"status": "refunded"}
- Workers
- 2: the first one stopped mid-run
- Answer
- Unopened, 4 days after delivery: §3 allows a refund. Recommend $62.00.
- After the restart
- returned its saved answer; the model wasn't called again
- Answer
- approve, from sam@acme.com
- After the restart
- returned the saved answer; nobody was asked twice
- What happened
- The worker running this run stopped when its machine restarted.
- Then
- A new worker picked the run up and ran handle_refund from the top. The agent and the approval returned their saved results.
- Ran
- once, on the new worker
- Result
- "re_8LmQ2c"
- Input
- {"order_id": "A-3381", "message": "Changed my mind about the espresso machine."}
- Output
- {"status": "declined"}
- 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
- Unused, 9 days after delivery: §3 allows a refund. Recommend $129.00.
- Tokens
- 1,412 in · 58 out
- Asked for
- lookup_order, then search_policy
- Input
- {"order_id": "A-3381"}
- Output
- {"item": "Espresso machine", "final_sale": true, …}
- Input
- {"question": "change of mind"}
- Output
- "§3 Change of mind: refund within 30 days for unused items."
- Tokens
- 1,772 in · 354 out
- Wrote
- Unused, 9 days after delivery: §3 allows a refund. Recommend $129.00.
- Answer
- reject, from sam@acme.com
- Comment
- "Final sale. We can't refund this."
- Scorer
- follows_refund_policy · online eval on 10% of runs
- Why it failed
- The agent recommended a $129.00 refund for order A-3381, which lookup_order returned with final_sale: true.
Fix it on the runs that failed.
Scorers grade live runs of handle_refund. When some fail, AGNT5 groups them into one issue, points at the code, and lets you test your fix on those same runs before it ships.
Read the improve docs91%passed this week
256runs scored (10% sample)
23failed
run 51d0Recommended a $129.00 refund on final-sale order A-3381run 7f3aRefund matches §2, damaged on arrivalrun a9c4Recommended a $74.00 refund on final-sale order A-3290run e04bRefund matches §3, unopenedrun 77e2Recommended a $210.00 refund on final-sale order A-3402
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. follows_refund_policy failed each one.
Likely causeThe agent’s instructions don’t mention final-sale orders, so it applies the change-of-mind rule to them. agents.py:7agents.ts:8agents.go:9
Fix promptIn src/support/agents.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/agents.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/agents.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 77e2run c310+ 19 more
6 model="anthropic/claude-sonnet-5-5", 7 instructions="""You resolve refund requests for Acme. 8 Look up the order first. Offer a refund only when the −policy allows it, and quote the policy when you do.""", 9+policy allows it, and quote the policy when you do. 10+Orders with final_sale set are not refundable: say so, 11+and offer store credit instead.""", 12 tools=[lookup_order, search_policy], 13 max_iterations=8,
7 modelName: 'anthropic/claude-sonnet-5-5', 8 instructions: `You resolve refund requests for Acme. 9 Look up the order first. Offer a refund only when the −policy allows it, and quote the policy when you do.`, 10+policy allows it, and quote the policy when you do. 11+Orders with final_sale set are not refundable: say so, 12+and offer store credit instead.`, 13 tools: [lookupOrder, searchPolicy], 14 maxIterations: 8,
8 9 const instructions = `You resolve refund requests for Acme. 10 Look up the order first. Offer a refund only when the −policy allows it, and quote the policy when you do.` 11+policy allows it, and quote the policy when you do. 12+Orders with final_sale set are not refundable: say so, 13+and offer store credit instead.` 14 15 var SupportAgent *agnt5.Agent
follows_refund_policy0 / 23 to 22 / 23
helpfulness21 / 23 to 22 / 23
cost per run$0.021 to $0.022
| Run | Order | Deploy 14 | Your change |
|---|---|---|---|
51d0 | A-3381 | refund $129.00 | store credit, final sale |
a9c4 | A-3290 | refund $74.00 | store credit, final sale |
77e2 | A-3402 | refund $210.00 | store credit, final sale |
c310 | A-3417 | refund $38.00 | store credit, final sale |
0b7d | A-3455 | refund $95.00 | partial refund $40.00 |
+ 18 more runs. Saved as the dataset final-sale-refunds, so later changes are tested on them too.
$ agnt5 deploy --env production ok Ready (51.2s) - 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.3s | no change |
| Cost per run | $0.021 | $0.022 | no change |
Issue #12 · fix shipped in deploy 15
If the failure comes back, Command Center reopens the issue.
Deploy 15 goes back to Run, where its runs are traced and scored
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 WorkersDeployment
Run it in our cloud or yours.
Use AGNT5 fully managed, or run it inside your own environment. If prompts, outputs, and customer data can’t leave your network, they don’t have to.
Deploy your first agent in 5 minutes.
Start free with 250K steps a month.