Skip to content

Wrap Up At Limits

End a run with a final answer when a usage limit would otherwise stop it with UsageLimitExceeded. Use it where the work done before the limit is worth returning, such as a research or coding agent running on a request, tool-call or token budget.

While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.

Usage

Terminal
pip install pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai.usage import UsageLimits
from pydantic_ai_harness import WrapUpAtLimits

agent = Agent('anthropic:claude-opus-5-5', capabilities=[WrapUpAtLimits()])


async def research(topic: str) -> str:
    result = await agent.run(topic, usage_limits=UsageLimits(request_limit=10, tool_calls_limit=30))
    return result.output

When the run’s UsageLimits leave room for one more model request but not for another after it, WrapUpAtLimits makes that request the last:

  • It sets tool_choice='none' and keeps the tool definitions, so the cached tools and instructions still match. Some providers still miss part of the cache: Anthropic caches messages per tool_choice, and some cases send a trimmed tool list. With tool output, tool_choice='none' sends only the output tools.
  • It adds a request-scoped instruction capability part, a WrapUpPart, asking the model to answer now with what it has. The model’s answer is the run’s output.
FieldDefaultMeaning
promptDEFAULT_WRAP_UP_PROMPTWhat the model is told on the final request

When the final request is made

LimitThe final request
request_limitThe last request the limit allows
tool_calls_limitThe first request after which the tool calls left are fewer than the run’s largest batch so far, or none are left
input_tokens_limit, output_tokens_limit, total_tokens_limitThe first request after which a final request is projected to go over the limit
  • A batch of tool calls larger than any before it that would go over tool_calls_limit still raises UsageLimitExceeded, before any of its calls run. Answering such a batch as not executed and wrapping up after it needs core to stop counting denied tool results against the limit (#8840); the request stays open in #11846.
  • Token use is projected from this run’s responses. Input and total tokens are assumed to grow on each further request by as much as the last response grew over the one before, plus the final prompt; output tokens to be at most the largest response’s. A final request that uses more than projected still raises UsageLimitExceeded.
  • cost_limit and per_request_input_tokens_limit aren’t projected, and raise as before.
  • If the final answer fails output validation, no request is left for the retry and the run raises UsageLimitExceeded.
  • A run given no usage_limits gets the default UsageLimits, whose request_limit is 50, so it wraps up on its 50th request instead of raising.
  • A model that still calls tools on the final request, as a provider that doesn’t enforce tool_choice='none' allows, has them run as usual, unless tool_calls_limit is used up, in which case they raise UsageLimitExceeded. After calls that ran, the next request is made the last again, or raises when no request is left.

Telling a wrapped-up answer from a finished one

The final prompt is a request-scoped WrapUpPart, an instruction capability part whose limit is the LimitName that triggered it. wrapped_up_by() reads it back:

from pydantic_ai import AgentRunResult
from pydantic_ai_harness import wrapped_up_by


def report(result: AgentRunResult[str]) -> str:
    if limit := wrapped_up_by(result.new_messages()):
        return f'{result.output}\n\n(cut short by `{limit}`)'
    return result.output

Durable execution

WrapUpAtLimits keeps no state of its own: it decides from the run’s usage and message history. Under durable execution its hooks run in workflow code, so when Temporal, DBOS or Prefect replays a run, they make the same request the last.

Telemetry

WrapUpAtLimits marks its decision with a zero-duration span on an instrumented agent:

SpanAttributeMeaning
run wrapped upwrap_up_at_limits.limitThe LimitName that made the request the last

The span carries no prompt text. The final request itself shows as an ordinary model request.

Composition

  • WarnNearLimits warns the model as limits approach. WrapUpAtLimits acts on the last request. Use both to have the model wind down first.
  • It decides on the usage when its hook runs. List it after capabilities that spend from the run’s usage before a request, such as SummarizingCompaction, so it sees what they spent.
  • Compaction still runs on the final request. A strategy that makes a model request of its own, such as SummarizingCompaction, has no request left there and raises UsageLimitExceeded; wrap it in FallbackCompaction(fallback_on=(UnexpectedModelBehavior, UsageLimitExceeded)) with a strategy that makes no model requests. Skipping compaction on the final request needs a core ordering hook (#11454).
  • In Subagents, give a sub-agent its own SubAgent.usage_limits and add WrapUpAtLimits to its capabilities: it returns a wrapped-up answer to the parent instead of reaching its budget. A sub-agent that shares the parent’s budget (no usage_limits of its own) would spend the parent’s last request on its answer, so the parent then raises.

See the source.

API reference

WrapUpAtLimits

Bases: AbstractCapability[AgentDepsT]

End the run with a final answer instead of raising when a usage limit would stop it.

When the run’s UsageLimits leave room for only one more model request, that request is made the last: it keeps the tool definitions with tool_choice='none', so the cached tools and instructions still match, and gets a request-scoped instruction asking the model to answer now. That prompt is a WrapUpPart carrying the limit that triggered it, which wrapped_up_by reads back.

from pydantic_ai import Agent
from pydantic_ai_harness import WrapUpAtLimits

agent = Agent('anthropic:claude-opus-5-5', capabilities=[WrapUpAtLimits()])

Attributes

prompt

What the model is told on the final request.

Type: str Default: DEFAULT_WRAP_UP_PROMPT

Methods

before_model_request

@async

def before_model_request(
    ctx: RunContext[AgentDepsT],
    request_context: ModelRequestContext,
) -> ModelRequestContext

Make this request the last when the limits leave no room for another one.

Returns

ModelRequestContext

wrapped_up_by

def wrapped_up_by(messages: Sequence[ModelMessage]) -> LimitName | None

The limit that made WrapUpAtLimits cut a run short, given the run’s new_messages(), or None.

Returns

LimitName | None

WrapUpPart

Bases: InstructionCapabilityPart

The request-scoped prompt WrapUpAtLimits adds to the final request.

Its content is the capability’s prompt, in the application’s voice. Find it in history by this type.

Attributes

limit

The limit that made the request the last. Never sent to the model.

Type: LimitName

LimitName

The UsageLimits field that made a request the run’s last.

Type: TypeAlias Default: Literal['request_limit', 'tool_calls_limit', 'input_tokens_limit', 'output_tokens_limit', 'total_tokens_limit']

DEFAULT_WRAP_UP_PROMPT

What WrapUpAtLimits tells the model on the final request, unless prompt is set.

Default: "This run's budget allows only this one last response, and tools are unavailable. Give your final answer now with what you have, and say what is left unfinished."