Agent Runtime¶

Session management and planning strategies for agentic loops.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Session¶

Symbol	Signature	Description
`Session`	`Session(principal: str, *, max_tokens: int = ..., pinned_count: int = 1)`	Carries state across `invoke()` calls: conversation history, token window, principal
`TokenWindow`	`TokenWindow(max_tokens: int, pinned_count: int = 1)`	Sliding token window with pinned opening messages and FIFO eviction

All planners share the same signature pattern and return a PlanResult.

Symbol	Signature	Description
`react.run`	`react.run(goal: str, *, llm: LLMClient, session: Session, ctx: Context \\| None = None, max_steps: int = 10, tools: ToolsSpec = None, tool_filter: ToolFilter = None, max_tokens_per_step: int = 1024, temperature: float = 0.0, max_cost_usd: float \\| None = None, max_tokens: int \\| None = None, max_wall_time_s: float \\| None = None) -> PlanResult`	Run a ReAct (Reason + Act) loop until the model finishes or budget is exhausted

Symbol	Signature	Description
`plan_and_execute.run`	`plan_and_execute.run(goal: str, *, llm: LLMClient, session: Session, ctx: Context \\| None = None, max_steps: int = 10, tools: ToolsSpec = None, tool_filter: ToolFilter = None, max_replans: int = 3, max_tokens_per_call: int = 1024, temperature: float = 0.0, max_cost_usd: float \\| None = None, max_tokens: int \\| None = None, max_wall_time_s: float \\| None = None) -> PlanResult`	Plan first, then execute steps. Replans up to `max_replans` times on failure

Symbol	Signature	Description
`reflexion.run`	`reflexion.run(goal: str, *, llm: LLMClient, session: Session, ctx: Context \\| None = None, max_steps: int = 10, tools: ToolsSpec = None, tool_filter: ToolFilter = None, max_outer_iterations: int = 3, max_tokens_per_call: int = 1024, temperature: float = 0.0, max_cost_usd: float \\| None = None, max_tokens: int \\| None = None, max_wall_time_s: float \\| None = None) -> PlanResult`	ReAct with self-reflection: runs inner loops and reflects on failures

Symbol	Signature	Description
`PlanResult`	`PlanResult(answer: str, steps: list[PlanStep], stop_reason: StopReason, ...)`	Return value from all planner `.run()` calls
`PlanStep`	`PlanStep(thought: str, action: str, observation: str, ...)`	One step in a planning loop
`StopReason`	`StopReason.FINISHED \\| .MAX_STEPS \\| .BUDGET \\| .WALL_TIME \\| .ERROR`	Why the planner stopped