Skip to content

AgentPool API Reference

Configuration store and service manager for agent orchestration.

Manages agent configurations, shared dependencies, MCP servers, skills, storage, and session orchestration. This is a pure config store — no agent instances are created at the pool level. Agents are defined in YAML config and instantiated on a per-session basis by SessionPool, which is the exclusive execution path.

Config metadata APIs: - main_agent_name: Resolved main agent name from config - main_agent_config: Main agent's AnyAgentConfig - agent_configs: All agent configs from the manifest - get_agent_display_name(): Display name for a configured agent

agent_configs property 

agent_configs: dict[str, AnyAgentConfig]

Get all agent configurations from the manifest.

Returns a direct reference to the manifest's agents dict, providing typed access to configuration metadata (display_name, description, model settings, etc.) without needing to know the manifest structure.

Use "agent_name" in pool.agent_configs for existence checks.

Returns:

Type Description
dict[str, AnyAgentConfig]

Dictionary mapping agent names to their AnyAgentConfig.

compaction_pipeline property 

compaction_pipeline: CompactionPipeline | None

Get the configured compaction pipeline or None if not configured.

extension_registry property 

extension_registry: ExtensionRegistry

Get the pool-level ExtensionRegistry.

Returns the ExtensionRegistry for global (pool-scoped) capability management.

graph property 

graph: Any

The pool's pydantic-graph topology.

Graph building was removed as part of eliminating pool-level agent creation. Config-based graphs (graph: YAML section) and runtime graphs (built from Talk connections) both required runtime agent instances to look up.

Returns:

Type Description
Any

Always None in the current implementation.

is_running property 

is_running: bool

Check if the agent pool is running.

main_agent_config property 

main_agent_config: AnyAgentConfig

Get the main agent configuration model.

Resolves :meth:main_agent_name and returns its config from self.manifest.agents.

This property works without calling __aenter__() — it only reads config data, not runtime agent instances.

Raises:

Type Description
RuntimeError

If no agents are configured.

main_agent_name property 

main_agent_name: str

Get the main agent name.

Returns the name specified by the main_agent_name constructor parameter, manifest.default_agent, or falls back to the first agent name from the manifest.

This property works without calling __aenter__() — it only reads config data, not runtime agent instances.

Raises:

Type Description
RuntimeError

If no agents are configured.

resource_capability property 

resource_capability: Any

Get the pool-scoped ResourceCapability instance.

Created during __aenter__ via _setup_resource_capability(). Returns None if not yet initialized.

session_pool property 

session_pool: SessionPool | None

Get the active SessionPool.

Returns the SessionPool instance when the pool is running, or None if not yet entered.

sessions property writable 

sessions: SessionPool | Any

Deprecated: use session_pool instead.

Returns the SessionPool instance when available.

skill_capabilities property 

skill_capabilities: list[Any]

Get pool-scoped SkillManagerCap instances.

These are created once in __aenter__ and rebuilt on dynamic skill registration/unregistration.

skill_resolver property 

skill_resolver: SkillURIResolver | None

Get the skill URI resolver.

Returns the SkillURIResolver for resolving skill:// URIs, or None if skills provider is not initialized.

__aenter__ async 

__aenter__() -> Self

Enter async context and initialize all agents.

__aexit__ async 

__aexit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None

Exit async context.

__init__ 

__init__(
    manifest: JoinablePathLike | AgentsManifest | None = None,
    *,
    shared_deps_type: type[TPoolDeps] | None = None,
    connect_nodes: bool = True,
    input_provider: InputProvider | None = None,
    parallel_load: bool = True,
    event_handlers: list[AnyEventHandlerType] | None = None,
    main_agent_name: str | None = None,
    session_pool_config: SessionPoolConfig | None = None,
    **kwargs: Any
)

Initialize agent pool with configuration loading.

Parameters:

Name Type Description Default
manifest JoinablePathLike | AgentsManifest | None

Agent configuration manifest

 None
shared_deps_type type[TPoolDeps] | None

Dependencies to share across all nodes

 None
connect_nodes bool

Whether to set up forwarding connections

 True
input_provider InputProvider | None

Input provider for tool / step confirmations / HumanAgents

 None
parallel_load bool

Whether to load nodes in parallel (async)

 True
event_handlers list[AnyEventHandlerType] | None

Event handlers to pass through to all agents

 None
main_agent_name str | None

Name of the main agent (overrides manifest.default_agent)

 None
session_pool_config SessionPoolConfig | None

Optional override for SessionPool configuration

 None
**kwargs Any

Additional keyword arguments (e.g., deprecated options).

 {}

Raises:

Type Description
ValueError

If manifest contains invalid configurations

add_server 

add_server(server: Any) -> None

Register a protocol server for consumer lifecycle management.

Parameters:

Name Type Description Default
server Any

A protocol server instance (e.g. ACPServer, OpenCodeServer).

 required

cancel_run 

cancel_run(run_id: str) -> None

Cancel an active run by its ID.

Parameters:

Name Type Description Default
run_id str

The run identifier to cancel.

 required

Raises:

Type Description
RuntimeError

If no session pool is available.
ValueError

If no active run with the given ID exists.

cleanup async 

cleanup() -> None

Clean up pool resources.

create_session async 

create_session(session_id: str, agent_name: str | None = None, **metadata: Any) -> Any

Create or get a session through the SessionPool.

Convenience method that delegates to the SessionPool's create_session method.

Parameters:

Name Type Description Default
session_id str

Unique identifier for the session.

 required
agent_name str | None

Name of the agent to associate with the session.

 None
**metadata Any

Arbitrary metadata to attach to the session.

 {}

Returns:

Type Description
Any

The session state from the SessionPool.

get_agent_display_name 

get_agent_display_name(name: str) -> str

Get the display name for a configured agent.

Returns the display_name from the agent's config if set, otherwise falls back to the agent name.

Parameters:

Name Type Description Default
name str

The agent name to look up.

 required

Returns:

Type Description
str

The display name, or the agent name if no display name is configured.

Raises:

Type Description
KeyError

If no agent with the given name exists in the manifest.

get_context 

get_context() -> HostContext

Return cached HostContext, creating it on first call.

If the cached context was created before __aenter__ set self._session_pool, the cache is rebuilt so that session_pool is up-to-date.

get_run 

get_run(run_id: str) -> RunHandle | None

Get a handle for an active run by its ID.

Parameters:

Name Type Description Default
run_id str

The run identifier to look up.

 required

Returns:

Type Description
RunHandle | None

The run handle if found and still active, otherwise None.

get_skill_instructions_for_node async 

get_skill_instructions_for_node(skill_name: str, node_name: str) -> str

Load skill instructions using a target node's package scope.

is_skill_visible_to_node 

is_skill_visible_to_node(skill: Any, node_name: str | None) -> bool

Return whether a skill is visible to a node's package scope.

list_active_runs 

list_active_runs() -> list[RunHandle]

List all currently active runs.

Returns:

Type Description
list[RunHandle]

List of active run handles, or empty list if no session pool.

register_skill_provider 

register_skill_provider(provider: AbstractCapability) -> None

Register a skill provider dynamically.

Adds the provider to the URI resolver and to the SkillManagerCap children so that its skills become visible to load_skill and list_skills. If called before _setup_skills_provider(), the provider is buffered and added when the resolver is created.

Parameters:

Name Type Description Default
provider AbstractCapability

The resource provider to register

 required

run_event_loop async 

run_event_loop() -> None

Run pool in event-watching mode until interrupted.

skill_scope_for_node 

skill_scope_for_node(node_name: str | None) -> str

Return the package-level skill scope for a node.

skill_scope_for_skill 

skill_scope_for_skill(skill: Any) -> str

Return the package-level skill scope for a skill.

track_message_flow async 

track_message_flow() -> AsyncIterator[MessageFlowTracker]

Track message flow during a context.

unregister_skill_provider 

unregister_skill_provider(provider: AbstractCapability) -> None

Unregister a previously registered skill provider.

Removes the provider from the URI resolver and from the SkillManagerCap children.

Parameters:

Name Type Description Default
provider AbstractCapability

The resource provider to unregister

 required