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.
pip install pydantic-ai-harness
uv add 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 pertool_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.
| Field | Default | Meaning |
|---|---|---|
prompt | DEFAULT_WRAP_UP_PROMPT | What the model is told on the final request |
| Limit | The final request |
|---|---|
request_limit | The last request the limit allows |
tool_calls_limit | The 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_limit | The 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_limitstill raisesUsageLimitExceeded, 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_limitandper_request_input_tokens_limitaren’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_limitsgets the defaultUsageLimits, whoserequest_limitis 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, unlesstool_calls_limitis used up, in which case they raiseUsageLimitExceeded. After calls that ran, the next request is made the last again, or raises when no request is left.
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
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.
WrapUpAtLimits marks its decision with a zero-duration span on an instrumented agent:
| Span | Attribute | Meaning |
|---|---|---|
run wrapped up | wrap_up_at_limits.limit | The LimitName that made the request the last |
The span carries no prompt text. The final request itself shows as an ordinary model request.
WarnNearLimitswarns the model as limits approach.WrapUpAtLimitsacts 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 raisesUsageLimitExceeded; wrap it inFallbackCompaction(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_limitsand addWrapUpAtLimitsto 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 (nousage_limitsof its own) would spend the parent’s last request on its answer, so the parent then raises.
See the source.
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()])
What the model is told on the final request.
Type: str Default: DEFAULT_WRAP_UP_PROMPT
@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.
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.
LimitName | None
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.
The limit that made the request the last. Never sent to the model.
Type: 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']
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."