Cross-Agent API Reference

Cross-agent communication utilities for Promptise Foundry. Exposes other in-process agents as standard LangChain tools so a primary agent can delegate to them during planning and execution. Supports per-peer ask tools and parallel broadcast to multiple peers.

CrossAgent

promptise.cross_agent.CrossAgent dataclass

Metadata wrapper for a peer agent to be exposed as a tool.

The wrapper is descriptive only. Behavior is implemented by tools produced via :func:make_cross_agent_tools.

Attributes:

Name	Type	Description
agent	Runnable[Any, Any]	A runnable agent (e.g., LangGraph or DeepAgents) that accepts {"messages": [...]} and returns a result consumable by the built-in “best final text” extractor.
description	str	One-line human description used in tool docs to help the calling agent decide when to delegate.
timeout	float | None	Seconds to wait for this peer's answer. None uses the timeout given to :func:make_cross_agent_tools (or delegation_timeout on :func:~promptise.agent.build_agent); when both are None the call has no limit of its own.

Examples:

>>> cross = CrossAgent(agent=peer_graph, description="Accurate math", timeout=60)

make_cross_agent_tools

promptise.cross_agent.make_cross_agent_tools(peers, *, tool_name_prefix='ask_agent_', include_broadcast=True, caller_identity=None, timeout=None, max_delegation_depth=DEFAULT_MAX_DELEGATION_DEPTH, on_before=None, on_after=None, on_error=None, requires_approval=None)

Create LangChain tools for cross-agent communication.

For each peer, a tool named f"{tool_name_prefix}{peer_name}" is created. Optionally, a broadcast_to_agents tool is added to fan-out questions to multiple peers concurrently.

Parameters:

Name	Type	Description	Default
peers	Mapping[str, CrossAgent]	Mapping of peer name → :class:CrossAgent. The name becomes part of the tool id (e.g., ask_agent_mathpeer).	required
tool_name_prefix	str	Prefix used for each per-peer ask tool. Defaults to "ask_agent_".	'ask_agent_'
include_broadcast	bool	When True (default here; build_agent defaults to False), also include the group fan-out tool broadcast_to_agents.	True
caller_identity	AgentIdentity | None	Identity of the delegating agent, announced to peers.	None
timeout	float | None	Seconds to wait for a peer that sets no :attr:CrossAgent.timeout of its own. None = no limit.	None
max_delegation_depth	int	Most nested delegations allowed in one request (1 = this agent may ask a peer, but that peer may not delegate further). Must be at least 1.	DEFAULT_MAX_DELEGATION_DEPTH
on_before	ToolHook | None	(tool_name, arguments) called before each peer call (used for trace_tools and observability).	None
on_after	ToolHook | None	(tool_name, result_text) called after a successful call.	None
on_error	ToolHook | None	(tool_name, exception) called when a call fails or is refused.	None
requires_approval	Callable[[str], bool] | None	The approval check of the agent that gets these tools (ApprovalPolicy.requires_approval), called with a tool name. broadcast_to_agents does not reach a peer whose ask_agent_<name> tool needs approval -- unless the broadcast tool needs approval itself -- because the broadcast would reach that peer without one. build_agent passes its approval policy here.	None

Returns:

Type	Description
list[BaseTool]	list[BaseTool]: A list of fully constructed tools ready to be appended
list[BaseTool]	to the caller agent’s toolset.

Raises:

Type	Description
ValueError	If max_delegation_depth is less than 1 or a timeout is not positive.

Notes

Construction does not contact peers; errors (e.g., network) surface at call time during execution of the generated tools.

Examples:

>>> tools = make_cross_agent_tools({
...     "researcher": CrossAgent(agent=peer_graph, description="Web research")
... })
>>> # Attach `tools` alongside your MCP-discovered tools when building the agent.