Agent-as-a-Tool — Patterns

A return type with an explicit failure variant

Problem. When the inner agent returns prose, failure is indistinguishable from success. "I could not find any matching records" and "there are no matching records" are the same string shape, and the caller treats both as findings.

Approach. Define a discriminated return: a status field drawn from a closed set — succeeded, no result, refused, exhausted, failed — alongside the payload, with the payload required only for the success case. Validate at the boundary and reject anything that does not conform, rather than passing a malformed value to the caller.

Trade-off. The inner agent must be able to classify its own outcome, which it will sometimes do wrongly, usually by reporting exhaustion as no result. It also constrains the inner agent to outcomes the designer anticipated, and genuinely novel situations get forced into the nearest category.

Budget in, accounting out

Problem. An inner agent with its own limits is invisible to the caller, so the caller cannot reason about total cost, and the inner run may spend minutes on something the caller needed an approximate answer to in seconds.

Approach. Pass a ceiling with the call — remaining time, maximum spend, maximum iterations — and return actual consumption with the result. The inner agent treats the ceiling as binding and returns its best partial answer with an exhausted status rather than failing when it hits one.

Trade-off. Callers must have a budget to pass, which means budget propagation has to exist throughout the system before this works. Inner agents also need a defined notion of a partial answer, which not every task has.

Handle and poll for long work

Problem. Synchronous invocation ties the caller's turn, the user's attention, and every proxy timeout along the path to the slowest possible inner run.

Approach. Return a handle immediately with an estimated completion, and expose status and result retrieval as separate operations. Let the caller decide whether to wait, do something else first, or tell the user it will take a while. Make the handle durable so a restart on either side does not lose the work.

Trade-off. The calling model has to be prompted into a multi-step interaction it does not naturally perform, and it will sometimes poll immediately in a tight loop or forget the handle entirely. Durable handles also require a store and an expiry policy.

Arguments only, no transcript

Problem. Forwarding the caller's conversation "so the inner agent has context" is the default in most frameworks and the simplest way to move data across an entitlement boundary without noticing.

Approach. Pass only declared arguments. If the inner agent needs background, make it an explicit, named, minimal argument the caller must deliberately populate. Give the inner run its own credentials scoped to what its task requires, rather than reusing the caller's.

Trade-off. Quality drops on tasks where ambiguity in the arguments could have been resolved from the conversation, and callers must now do work to supply what the interface demands. That work is the point: it makes the data crossing the boundary a decision rather than a default.