Skip to content

API reference

Everything below is importable from adk_agent_harness.

Factory

create_deep_agent 

create_deep_agent(
    *,
    name: str,
    model_client: str | BaseLlm,
    instruction: str,
    description: str = "",
    tools: Sequence[ToolUnion] = (),
    skills: SkillToolset | None = None,
    thinking: bool | ThinkingConfig = False,
    compaction: CompactionConfig | None = None,
    plugins: Sequence[BasePlugin] = (),
    subagents: Sequence[SubAgentSpec] = (),
    spawn: SpawnConfig | None = None,
    elicitation: bool = False,
    available_models: Sequence[str | ModelSpec] = (),
    sandbox: SandboxKind
    | SandboxConfig
    | BaseEnvironment
    | None = None,
    context_cache: bool | ContextCacheConfig | None = None,
) -> App

Create a standard ADK App with deep-agent behavior pre-wired.

The returned App always includes the built-in todo task ledger, active ledger injection before each root model request, and ToolCallRepairPlugin. Everything else is opt-in. Run the App with any ADK Runner and the session, artifact, and memory services your application chooses.

Parameters:

Name Type Description Default
name str

Root agent and App name. Must be a valid Python identifier and cannot be user.

 required
model_client str | BaseLlm

Root model. A model name string or any ADK BaseLlm, such as LiteLlm.

 required
instruction str

Root agent instruction. Package guidance for the enabled features is appended to it.

 required
description str

Optional root agent description.

 ''
tools Sequence[ToolUnion]

Tools for the root agent: functions, ADK BaseTool or BaseToolset values, including MCP toolsets.

 ()
skills SkillToolset | None

One ADK SkillToolset for the root agent.

 None
thinking bool | ThinkingConfig

True, False, or a ThinkingConfig; mapped to ADK's BuiltInPlanner.

 False
compaction CompactionConfig | None

Optional CompactionConfig enabling ADK event compaction with a summary prompt written for long-running work.

 None
plugins Sequence[BasePlugin]

Additional ADK plugins for the App. ToolCallRepairPlugin is always installed first.

 ()
subagents Sequence[SubAgentSpec]

Prebuilt children declared with SubAgentSpec, attached as native ADK sub_agents.

 ()
spawn SpawnConfig | None

SpawnConfig(enabled=True, ...) adds the spawn_subagent tool so the root agent can create temporary children at runtime, in the foreground or in the background.

 None
elicitation bool

Add ADK's request_input tool to the root agent and make the App resumable, for structured questions to the user.

 False
available_models Sequence[str | ModelSpec]

Models a spawned child may select, as IDs or ModelSpec values. The root model is always included as the default. Only IDs and descriptions reach the model.

 ()
sandbox SandboxKind | SandboxConfig | BaseEnvironment | None

Optional workspace for shell and file tools. Accepts a backend name (local, daytona, e2b, cloud_run), a SandboxConfig, or a preconstructed ADK BaseEnvironment. Filesystem backends attach ADK's EnvironmentToolset; cloud_run attaches ADK's Cloud Run sandbox code executor instead. Credentials are preflighted here. One environment is created per App and shared by all its sessions.

 None
context_cache bool | ContextCacheConfig | None

Optional ADK context caching. True uses ADK defaults; pass an ADK ContextCacheConfig to tune intervals and TTL.

 None

Returns:

Type Description
App

A standard google.adk.apps.App.

Raises:

Type Description
ValueError

For invalid or duplicate agent names, or a subagent that requests a sandbox when none is configured.
SandboxConfigurationError

When a selected sandbox backend is missing credentials or packages.

Configuration

SubAgentSpec

Bases: BaseModel

A prebuilt subagent, attached as a native ADK sub_agent.

ADK exposes it to the root agent as a tool named after the subagent, runs it on its own branch of the root session, and streams its events in the root run_async() stream.

name instance-attribute 

name: str

Child name and tool name. A valid Python identifier, unique in the App.

goal instance-attribute 

goal: str

What the child does. Used for its default instruction and description.

instruction class-attribute instance-attribute 

instruction: str | None = None

Full instruction. Overrides the instruction generated from goal.

description class-attribute instance-attribute 

description: str = ''

Tool description shown to the root agent. Defaults to goal.

model_client class-attribute instance-attribute 

model_client: str | BaseLlm | None = None

Model for this child. Defaults to the root model.

tools class-attribute instance-attribute 

tools: Sequence[ToolUnion] = ()

Tools for this child only.

skills class-attribute instance-attribute 

skills: SkillToolset | None = None

One ADK SkillToolset for this child.

mode class-attribute instance-attribute 

mode: SubAgentMode = 'single_turn'

ADK subagent mode.

thinking class-attribute instance-attribute 

thinking: bool | ThinkingConfig = False

Thinking settings for this child.

use_sandbox class-attribute instance-attribute 

use_sandbox: bool = False

Grant this child the root agent's configured sandbox workspace.

SpawnConfig

Bases: BaseModel

On-demand spawned subagent configuration.

Enabling it adds the spawn_subagent tool. Spawned children always run in ADK single_turn mode: they complete the delegated request once, without user interaction, and return a result. The root agent chooses per call whether to wait (the default) or run the child in the background.

enabled class-attribute instance-attribute 

enabled: bool = False

Add the spawn_subagent tool to the root agent.

tools class-attribute instance-attribute 

tools: Mapping[str, ToolUnion] = Field(default_factory=dict)

Extra tools spawned children may use, by name. The root agent's own tools and the sandbox (environment) are offered too.

skills class-attribute instance-attribute 

skills: Mapping[str, SkillToolset] = Field(
    default_factory=dict
)

Skill toolsets spawned children may use, by name.

allowed_tools class-attribute instance-attribute 

allowed_tools: Sequence[str] = ()

Tool names a child may select. Empty allows every registered tool.

allowed_skills class-attribute instance-attribute 

allowed_skills: Sequence[str] = ()

Skill names a child may select. Empty allows every registered skill.

ModelSpec

Bases: BaseModel

A model exposed to the root agent for spawned-agent selection.

id instance-attribute 

id: str

ID the model selects in spawn_subagent(model=...).

model_client class-attribute instance-attribute 

model_client: str | BaseLlm | None = None

Model name or ADK BaseLlm. Defaults to id. Never shown to the model.

description class-attribute instance-attribute 

description: str = ''

When to use this model, shown to the root agent.

capabilities class-attribute instance-attribute 

capabilities: Sequence[str] = Field(default_factory=tuple)

Short capability tags shown to the root agent, such as reasoning.

ThinkingConfig

Bases: BaseModel

Model thinking settings, mapped to ADK's BuiltInPlanner.

enabled class-attribute instance-attribute 

enabled: bool = True

Turn thinking on. False attaches no planner.

include_thoughts class-attribute instance-attribute 

include_thoughts: bool = False

Ask the model to return thought summaries, so a UI can show reasoning.

thinking_budget class-attribute instance-attribute 

thinking_budget: int | None = None

Maximum thinking tokens. None uses the model default.

CompactionConfig

Bases: BaseModel

ADK event compaction settings.

When the latest prompt exceeds token_threshold, older events are summarized with a prompt written for long-running work. The task ledger is stored separately in session state and is never lost to compaction.

token_threshold class-attribute instance-attribute 

token_threshold: int = Field(gt=0)

Prompt token count that triggers compaction.

event_retention_size class-attribute instance-attribute 

event_retention_size: int = Field(default=20, ge=0)

Number of most recent events kept verbatim after compaction.

compaction_interval class-attribute instance-attribute 

compaction_interval: int = Field(default=999, gt=0)

ADK's invocation-count trigger. The high default leaves compaction driven by token_threshold.

overlap_size class-attribute instance-attribute 

overlap_size: int = Field(default=0, ge=0)

Events shared between consecutive compaction windows.

SandboxConfig

Bases: BaseModel

Declarative sandbox configuration for create_deep_agent.

working_dir class-attribute instance-attribute 

working_dir: str | Path | None = None

local only. Workspace directory; a temporary one is used when unset.

image class-attribute instance-attribute 

image: str | None = None

daytona and e2b only. Template, snapshot, or image name.

timeout class-attribute instance-attribute 

timeout: int = Field(default=300, gt=0)

daytona and e2b only. Sandbox time-to-live in seconds.

api_key class-attribute instance-attribute 

api_key: str | None = None

daytona and e2b only. Overrides the backend API-key env var.

api_url class-attribute instance-attribute 

api_url: str | None = None

daytona only. Overrides DAYTONA_API_URL.

env_vars class-attribute instance-attribute 

env_vars: Mapping[str, str] = Field(default_factory=dict)

Environment variables set inside the sandbox, not in this process.

max_output_chars class-attribute instance-attribute 

max_output_chars: int | None = None

Truncation limit applied to sandbox tool output before the model sees it.

sandbox_bin class-attribute instance-attribute 

sandbox_bin: str | None = None

cloud_run only. Overrides the guest sandbox binary path.

allow_egress class-attribute instance-attribute 

allow_egress: bool = False

cloud_run only. Whether the sandbox may reach the network.

validate_environment class-attribute instance-attribute 

validate_environment: bool = True

Preflight credentials and packages while building the agent.

Background subagents

BackgroundTask

Bases: BaseModel

Status of one background spawned subagent.

task_id instance-attribute 

task_id: str

ID returned by spawn_subagent(..., background=True).

name instance-attribute 

name: str

Child agent name.

goal instance-attribute 

goal: str

Delegated goal.

model instance-attribute 

model: str

Model ID the child runs on.

parent_session_id instance-attribute 

parent_session_id: str

Root session that started the task.

result class-attribute instance-attribute 

result: Any = None

Final text of the child, once completed.

error class-attribute instance-attribute 

error: str | None = None

Failure or cancellation detail.

get_background_task 

get_background_task(task_id: str) -> BackgroundTask | None

Return the current status of one background task.

list_background_tasks 

list_background_tasks(
    *,
    session_id: str,
    app_name: str | None = None,
    user_id: str | None = None,
) -> list[BackgroundTask]

Return background tasks started from one root session, oldest first.

stream_background_task_events async 

stream_background_task_events(
    task_id: str,
) -> AsyncIterator[Event]

Yield the child's raw ADK events: buffered ones first, then live ones.

The iterator ends when the background task finishes.

wait_for_background_task async 

wait_for_background_task(task_id: str) -> BackgroundTask

Wait until a background task finishes and return its final status.

cancel_background_task 

cancel_background_task(task_id: str) -> bool

Cancel a running background task. Returns False if it already finished.

Asking the user

ElicitationRequest

Bases: BaseModel

Stable UI-facing projection of an ADK request_input interruption.

id instance-attribute 

id: str

Function-call ID. The resume response must carry the same ID.

message instance-attribute 

message: str

Question to show the user.

response_schema class-attribute instance-attribute 

response_schema: dict[str, Any] | None = None

JSON Schema for the answer, for rendering a form.

invocation_id instance-attribute 

invocation_id: str

Interrupted invocation to resume with Runner.run_async(invocation_id=...).

author instance-attribute 

author: str

Agent that asked the question.

raw_event class-attribute instance-attribute 

raw_event: Event = Field(exclude=True)

The original ADK event.

project_elicitation_event 

project_elicitation_event(
    event: Event,
) -> ElicitationRequest | None

Project an ADK request_input function call for a client UI.

create_elicitation_response 

create_elicitation_response(
    request: ElicitationRequest, answers: Any
) -> Content

Build the user-role FunctionResponse that resumes an elicitation.

Interrupted tool calls

ToolCallRepairPlugin 

ToolCallRepairPlugin(
    name: str = TOOL_CALL_REPAIR_PLUGIN_NAME,
)

Bases: BasePlugin

Answer dangling tool calls before every model request.

repair_dangling_tool_calls 

repair_dangling_tool_calls(contents: list[Content]) -> int

Insert synthetic results for unanswered tool calls, in place.

Returns the number of synthetic results inserted.

Sandbox helpers

SandboxConfigurationError

Bases: RuntimeError

Raised when a sandbox backend is selected but not usable.

missing_sandbox_requirements 

missing_sandbox_requirements(
    config: SandboxConfig,
) -> list[str]

Return unmet requirements for a sandbox config, in report order.

describe_sandbox_requirements 

describe_sandbox_requirements(kind: SandboxKind) -> str

Return human-readable setup requirements for one sandbox backend.

sandbox_requirements_report 

sandbox_requirements_report(
    kinds: Sequence[SandboxKind] = (
        "local",
        "daytona",
        "e2b",
        "cloud_run",
    ),
) -> str

Return setup requirements for the given sandbox backends.

SandboxRequirements

Bases: BaseModel

Environment variables and packages one sandbox backend needs.

Task ledger

TaskLedgerItem

Bases: BaseModel

One task item in the deep-agent ledger.

TaskLedgerResult

Bases: BaseModel

Tool response returned by the built-in todo tool.

TaskLedgerSummary

Bases: BaseModel

Counts for the current ledger.

Constants

Name Value Meaning
LEDGER_STATE_KEY "adk_agent_harness:todos" Session state key holding the task ledger
REQUEST_INPUT_TOOL_NAME "adk_request_input" ADK's elicitation tool name
SANDBOX_TOOLSET_NAME "environment" Tool name spawned subagents use to get the sandbox
SANDBOX_REQUIREMENTS dict Install and environment requirements per sandbox backend