Module codeact 

Available on crate features agents and codeact only.

A CodeAct agent: a peer to LlmAgent that acts by writing and executing code instead of emitting one tool call at a time.

The framework is language-agnostic — the CodeRuntime defines the language (Python via Monty, JavaScript, a shell, …) and reports it to the agent.

The loop

Each turn, the model produces one code script. Tools are exposed as functions the model can call and compose. The script communicates its result by returning a tagged value — a ScriptOutput variant — which the host classifies:

• ScriptOutput::Observation is fed back to the model for the next turn,
• ScriptOutput::Error is fed back as an opaque message string,
• ScriptOutput::FinalResult ends the loop and is returned to the caller, and
• ScriptOutput::TransferToAgent ends the loop and hands control to another agent.

Errors are just strings produced by the runtime in whatever form the model expects (a traceback, a stack, …); any error consumes a model turn. When a tool fails, that surfaces as an error raised into the script.

Transfer to another agent

Like LlmAgent, a CodeActAgent can hand control to a sub-agent or to a peer/parent the Runner supplies via RunConfig::transfer_targets. The transfer output is only described to the model when at least one target exists; a transfer emits an event carrying EventActions::transfer_to_agent and ends the run, exactly as the LlmAgent’s transfer_to_agent tool does. An unknown target is fed back to the model as an error instead of transferring.

Deferred tool calls (HITL and long-running)

The script never decides to suspend. The host defers a tool call when it cannot resolve inline:

• a confirmation-gated tool with no decision yet, or
• a long-running tool whose result arrives out-of-band.

In both cases the agent serializes the live interpreter continuation into a CodeActCheckpoint and writes it to session state (via an event’s state_delta), then ends the run — exactly the “save to session, rebuild, continue” model of LlmAgent. On the next invocation Agent::run reads the checkpoint back and resumes: the confirmation decision arrives via RunConfig::tool_confirmation_decisions, and a long-running result arrives as a FunctionResponse in the new message. There is no out-of-band resume API and no side store — the Runner re-invokes run() and the agent self-routes.

This requires a runtime that can snapshot/resume. A runtime that cannot runs long-running tools inline and rejects confirmation pauses.

Tool side effects

Like LlmAgent, tool-produced session changes are propagated: any state_delta/artifact_delta/route a tool sets on its ToolContext is merged onto the next persisted event (a checkpoint, or the final event when the runtime cannot checkpoint), and a tool that sets escalate, skip_summarization, or transfer_to_agent ends the run immediately, forwarding that signal to the Runner. This is what lets an AgentTool wrapping a sub-agent forward that sub-agent’s state back to the session.

Each tool call runs against a fresh per-call ToolContext that carries the interpreter’s call id and otherwise delegates artifacts, memory, shared state, user scopes, and secrets to the live invocation — so a tool behaves identically whether it is driven by a CodeActAgent or an LlmAgent.

Capabilities (parity with LlmAgent)

A CodeActAgent mirrors LlmAgent’s configuration surface, differing only where the CodeAct loop demands it:

• Model: generate_content_config plus temperature/top_p/top_k/ max_output_tokens shorthands.
• Instructions (assembled per invocation): instruction and instruction_provider, global_instruction (+ provider), with {state.key} template injection; the selected skill block, when a skills index is configured (skills feature).
• History: include_contents controls how much session history seeds the transcript.
• Tools: static tools plus per-invocation toolsets; tool_timeout, default_retry_budget/tool_retry_budget, circuit_breaker_threshold, and on_tool_error fallbacks.
• Confirmation & transfer: ToolConfirmationPolicy, sub-agents and the disallow_transfer_to_parent/disallow_transfer_to_peers flags.
• Output: output_key, and output_schema/output_type validated with a correction-retry loop (output_max_retries).
• Lifecycle & interception hooks: before/after-agent callbacks (after-agent runs on normal completion, not on suspension, transfer, or escalation), before/after-model callbacks (rewrite or short-circuit the model call), and before/after-tool callbacks plus the rich after_tool_callback_full (rewrite or short-circuit a tool call).
• Feature-gated: input/output guardrails (guardrails), skills (skills), and the EnhancedPlugin pipeline intercepting tool and model calls (enhanced-plugins).

Deliberate non-matches: code-execution sandboxing is the CodeRuntime’s responsibility (not a bolt-on); tool dispatch is sequential by design (see runtime), so there is no tool_execution_strategy/concurrency knob; and the agent has no skip_summarization builder option — the model ends the loop itself via ScriptOutput::FinalResult — though a tool that sets skip_summarization on its actions still ends the run.

Runtime

Execution runs on a CodeRuntime, the step-wise interpreter seam. The production adapter wraps Monty, a Rust-native Python interpreter whose snapshot-at-call-boundary model makes suspend/resume a true continuation rather than a replay. It lives in the adk-codeact-monty crate.

Modules

agent

The CodeActAgent and its streaming loop.

checkpoint

The suspend/resume payload, persisted in session state.

error_map

Error-message helpers for the strings raised into scripts and fed back to the model.

output

The typed value a script returns to the host.

runtime

The step-wise interpreter seam — language-agnostic.

Structs

CodeActAgent

A configured CodeAct agent.

CodeActAgentBuilder

Builder for CodeActAgent.

CodeActCheckpoint

A serializable snapshot of a suspended CodeAct run, stored in session state.

PendingToolCall

The tool call a suspended run is waiting on.

RuntimeCapabilities

What a CodeRuntime reports about itself.

Enums

Disposition

Why a checkpoint was written, and how to resume from it.

ResumeWith

How to resume a paused external-function call.

RunStep

The result of advancing the interpreter to its next host-relevant stop.

RuntimeError

A host-level failure of the runtime itself (not a script-level error).

ScriptOutput

The typed value a CodeAct script must return.

Constants

CODEACT_SYSTEM_PROMPT

The default, language-agnostic CodeAct system prompt.

DEFAULT_MAX_ERROR_CHARS

Default cap (in chars) on an error message fed back to the model.

DEFAULT_MAX_ITERATIONS

Default number of model turns before the loop gives up.

PENDING_STATE_KEY

Session-state key under which the pending checkpoint is stored.

Traits

CodeRuntime

A step-wise, language-agnostic code interpreter capable of suspend/resume at call boundaries.

PendingCall

A paused external-function call awaiting a result.

Functions

bind_call_args

Bind a call’s positional and keyword arguments onto a tool’s parameters, producing the single JSON object a Tool expects.

build_tool_map

Build a ToolMap from a tool list, excluding built-in (server-side) tools which cannot be invoked from a script.

default_tool_catalog

A generic, language-neutral tool listing.

denied_message

Message raised when a human denies a confirmation-gated tool call.

extract_code_block

Extract the body of the first fenced code block, skipping any language tag on the fence line. Falls back to the trimmed input when no fence is present.

tool_error_message

Message raised into the script when a tool fails.

unknown_tool_message

Message raised when the script calls a tool that is not registered.

Type Aliases

ToolMap

A tool lookup table keyed by tool name.