← Back to learning path
Case · Published

Case study: an evidence package and human handoff after an agent failure

Turn tool traces, failure reasons, and next-step advice into an auditable handoff record.

Source: knowledge/p27/ai-agent-engineering/cases/agent-evidence-handoff.mdAI agent engineering
Chapter progress 0%Learning path progress 0% · 0/10 chapters completedContinue learning path →

Problem and boundaries

When an external system times out, a ticket agent must not keep guessing. This case uses an in-memory event list to verify pausing, evidence summaries, and human handoff without calling an external service.

Design

Each event stores only the tool name, status, duration, and a redacted parameter summary. When the retry budget is exhausted or a permission error occurs, the system writes a handoff event. The interface shows the next action instead of pretending the task completed.

Minimal implementation

events = []
events.append({'type': 'tool', 'name': 'lookup_ticket', 'status': 'timeout', 'attempt': 2})
events.append({'type': 'handoff', 'reason': 'dependency_timeout', 'next': 'verify manually'})
assert events[-1]['type'] == 'handoff'
assert all('secret' not in event for event in events)

Reproduction steps

  1. Create a fixed ticket input and a simulated timeout tool with at most two retries.
  2. Record tool events and error codes without storing the complete user body or credentials.
  3. Write a handoff event and show the ticket id, failure reason, and suggested action in the human interface.
  4. Append a resolution event after the human finishes, keeping the original failure trace for regression tests.

Verification checklist

Check the retry limit, immediate handoff on permission errors, evidence redaction, and duplicate submission without creating a second ticket.

Common questions

Is a human handoff the same as a failure? It is a controlled safety state and should be counted separately from system errors.

Can the handoff be sent back to the model automatically? Only with human authorization and a new budget.

Further reading

Official references

OpenAI Agents guide; OWASP LLM Top 10.

Last checked: 2026-11-17. Follow the linked sources for current interfaces and security boundaries; this case makes no performance or cost claim.

Prerequisite tutorials

KnowledgeAgent production release: canary, rollback, and human handoffKnowledgeAgent 重试、幂等与证据:让失败可以恢复 (original language)

Further reading

KnowledgeAI Agents: From Core Concepts to ProductionKnowledgeProduction Prompt Engineering: From Instructions to Measurable ContractsKnowledgeStructured Outputs and Tool Contracts for Safe Agents
Product Hub Demo · V0.3