Error Propagation

This mechanism captures raw exceptions from external APIs or tools and wraps them in a standardized, structured format that an AI agent can parse. The wrapper enriches the raw error with contextual metadata.

• Structured Error Objects: Raw exceptions (e.g., HTTP 404, database connection timeout) are transformed into JSON objects with fields like error_code, message, tool_name, timestamp, and suggested_remediation.
• Semantic Enrichment: Adds agent-readable context, such as classifying the error as NETWORK_FAILURE, AUTHENTICATION_ERROR, or RESOURCE_NOT_FOUND. This allows the LLM to reason about the failure type without parsing low-level technical messages.
• Example: A ConnectionRefusedError on port 5432 is wrapped as {"type": "DATABASE_UNAVAILABLE", "original_message": "Connection refused", "severity": "HIGH", "retryable": true}.

The propagation system injects the structured error description directly into the LLM's context window, modifying its subsequent reasoning loop. This is the core feedback mechanism.

• Context Augmentation: The error object is appended to the agent's message history or system prompt, often with a directive like The previous tool call failed with the following error: [ERROR_OBJECT]. Analyze this and decide the next action.
• Maintaining State: The failed call and its parameters remain in the agent's working memory, preventing it from blindly repeating the same invalid request.
• Enabling Reflection: This injected context allows the agent to execute a ReAct-style reasoning step, where it Thinks about the cause of the error before Acting again, potentially selecting a different tool or reformulating parameters.

The middleware or orchestration engine (e.g., LangChain, Semantic Kernel) acts as a router, deciding where to send the error signal based on predefined policies and the workflow's state.

• Destination Decision Logic: Determines if the error should be sent back to the main agent loop, a specialized sub-agent for error handling, a human-in-the-loop queue, or a monitoring dashboard.
• Circuit Breaker Integration: Propagates failures to a circuit breaker pattern. After N consecutive failures for a specific service, the orchestration layer may stop propagating errors for that tool and instead inject a SERVICE_UNAVAILABLE signal, forcing the agent to use a fallback.
• Workflow Context: Uses the state of a tool chain to decide if the error is fatal to the entire workflow or if execution can branch to an alternative path.

Error propagation systems are tightly integrated with retry policies. The propagation mechanism communicates whether a failure is retryable and coordinates the retry attempts.

• Retryable Flag: The wrapped error object includes a boolean retryable flag, often determined by the error type (e.g., a rate limit error is retryable; an invalid API key is not).
• Exponential Backoff Signaling: The propagation layer can inject waiting instructions or manage the retry loop externally, preventing the agent from immediately resending a request that will likely fail again.
• Attempt Counting: The number of previous retry attempts for the current operation is included in the propagated context, allowing the agent to give up after a threshold and try a fundamentally different approach.

Propagated errors act as the primary trigger for executing predefined fallback strategies. The mechanism provides the necessary context for the system to select an appropriate alternative.

• Strategy Selection: Based on the error's type and tool_name, the system can map to a registered fallback. For example, a SEARCH_API_FAILURE error might trigger a fallback to a cached vector database search.
• Parameter Adaptation: The propagated error includes the original call parameters, allowing the fallback tool to be invoked with modified or simplified inputs.
• Graceful Degradation: The ultimate goal is to propagate not just failure, but a pathway to partial success. The mechanism enables the agent to reason: "Tool X failed, so I will use Tool Y, which may provide less precise but available data."

Every propagated error is also routed to observability systems, creating an immutable audit trail for debugging, compliance, and improving system resilience.

• Structured Logging: The enriched error object is sent to logging platforms (e.g., OpenTelemetry, Datadog) with the full context of the agent's session, user ID, and workflow ID.
• Metric Generation: Errors are counted and categorized to generate SLOs/SLIs (Service Level Objectives/Indicators) for AI-agent reliability, such as tool_call_success_rate.
• Feedback Loop for Fine-Tuning: Logs of propagated errors, along with the agent's successful recovery actions, create datasets for reinforcement learning from human feedback (RLHF) or fine-tuning to improve the agent's innate error-handling reasoning.

The systematic strategies and patterns for managing API failures and transient errors in autonomous execution. This includes:

• Circuit breakers to prevent cascading failures by temporarily blocking calls to a failing service.
• Exponential backoff with jitter for retrying failed calls, increasing wait times between attempts to avoid overwhelming the target system.
• Fallback mechanisms that provide alternative data sources or default responses when a primary service is unavailable.
• Timeout management to bound the maximum wait time for any external call, ensuring system responsiveness.

Predefined contingency plans that an AI system executes when a primary tool call fails. These are essential for maintaining service continuity and user experience. Common strategies include:

• Alternative Tool Invocation: Automatically calling a different API or service that provides similar functionality.
• Cached Response Delivery: Serving a recent, valid result from a local cache if the live call fails.
• Graceful Degradation: Providing a simplified but functional response using the agent's native knowledge, perhaps with a disclaimer about data freshness.
• User Delegation: Prompting the human user to complete the action manually when automated recovery is not possible.

A resilience pattern that monitors for failures in a service dependency. When failures exceed a defined threshold (e.g., 5 failures in 30 seconds), the circuit "opens" and all subsequent calls immediately fail without attempting the network request. This allows the failing service time to recover and prevents resource exhaustion in the calling system. After a configured reset period, the circuit moves to a "half-open" state to test if the service is healthy before fully closing and resuming normal operation. It is a foundational pattern for preventing cascading failures in distributed systems involving AI agents.

A configurable set of rules governing the automatic re-attempt of failed API or tool calls. Effective policies are crucial for handling transient errors like network timeouts or temporary server overload (5xx HTTP status codes). Key configuration parameters include:

• Maximum Retry Count: The total number of re-attempts before definitive failure.
• Backoff Strategy: The algorithm for increasing wait times between retries (e.g., exponential, linear).
• Retryable Status Codes: Defining which HTTP responses or exception types should trigger a retry.
• Jitter: Adding random variation to backoff intervals to prevent synchronized retry storms from multiple clients. Policies must avoid retrying non-idempotent operations (like payments) or client errors (4xx codes) where retry is futile.

The programmatic verification of API call inputs and outputs against defined schemas to ensure correctness and safety before and after execution. This acts as a first line of defense against malformed requests and unexpected data that could cause downstream errors.

• Pre-execution validation checks that parameters extracted from the AI model's output conform to the expected JSON Schema types, ranges, and required fields.
• Post-execution validation ensures the external service's response matches the expected structure before it is passed back to the AI agent for reasoning.
• This process catches errors early, providing clear, actionable feedback for error propagation instead of cryptic runtime failures.

The architecture of the middleware and control plane software that sequences, manages state, and monitors tool calls within an AI agent workflow. This layer is responsible for implementing error propagation logic. Key functions include:

• Workflow State Management: Tracking the progress and results of a multi-step plan, including which steps have succeeded or failed.
• Error Routing: Deciding where to send a failure notification—back to the agent for replanning, to a monitoring system, or to a human operator.
• Compensation Actions: Triggering rollback procedures or corrective actions when a step in a tool chain fails.
• Observability Integration: Emitting detailed logs, metrics, and traces for every tool invocation and its outcome, which is critical for debugging propagated errors.