Skip to main content

​
spawn

A function to spawn an agent. 
async def spawn(
    premise: str | None = None,
    scope: dict[str, Any] | None = None,
    *,
    system: str | template | None = None,
    mcp: str | None = None,
    model: ModelStrings = DEFAULT_AGENT_MODEL,
    listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
    max_tokens: int | MaxTokens = MaxTokens.default(),
) -> Agent:
    ...
Parameters
​
premise
str | None
An optional premise for the agent. This will be attached to the system prompt of all invocations of this agent.
This argument cannot be provided along with the system argument and will not be formatted if using template.
​
scope
dict[str, Any] | None
An optional default set of resources which the agent will have access to indefinitely. Resources in scope may be arbitrary Python functions, methods, objects, iterators, types or any other Python value. These resources may additionally be specified per invocation later on.
​
system
str | None
An optional system prompt for the agent. This will be the system prompt of all invocations of this agent.
This argument cannot be provided along with the premise argument.
​
mcp
str | None
The string of a path to a .json file representing an MCP configuration. Any servers and/or tools of servers outlined in the config can be used during the agent’s run.
​
command
string
required
The executable command to run the MCP server. This should be an absolute path or a command available in the system PATH.Example:
"python"
​
args
array of string
An array of command-line arguments passed to the server executable. Arguments are passed in order.Example:
["server.py", "--verbose", "--port", "8080"]
​
env
object
An object containing environment variables to set when launching the server. All values must be strings.Example:
{
    "API_KEY": "secret-key",
    "PORT": "8080"
}
​
model
str
The model which backs your agent.One of:
  • 'openai:gpt-3.5-turbo'
  • 'openai:gpt-4o'
  • 'openai:gpt-4.1'
  • 'openai:gpt-5'
  • 'anthropic:claude-sonnet-4'
  • 'anthropic:claude-opus-4.1'
  • 'anthropic:claude-sonnet-4.5'
  • 'anthropic:claude-opus-4.5'
or any OpenRouter model slug.
The default model is openai:gpt-4.1.
​
max_tokens
int | MaxTokens
Either
  • the maximum number of output tokens generated in a single round of inference in a single invocation, or
  • an instance of MaxTokens for more fine-grained control.
See MaxTokens for information on default values.
​
listener
Callable[[], AgentListener] | DefaultAgentListener | None
Optional listener constructor for logging the agentic function’s activity and chat history.
The default agent listener is the StandardListener, but can be changed for all agents and agentic functions in the current scope with set_default_agent_listener. If a context-specific logger is used in the current scope, the logger will be added to the listener: if the listener is None, then the listener will be set to:
  • the default agent listener, if it is not None, or
  • the StandardListener, if the default agent listener is None
For more information on the StandardListener and the listener heirarchy, see here.
​
Returns
Agent
The agent that was spawned.

​
Agent.__init__

A method to directly instantiate an agent. 
class Agent:

  def __init__(
    self,
    premise: str | None = None,
    scope: dict[str, Any] | bytes | None = None,
    *,
    system: str | template | None = None,
    mcp: str | None = None,
    model: ModelStrings = DEFAULT_AGENT_MODEL,
    listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
    max_tokens: int | MaxTokens = MaxTokens.default(),
  )
Parameters See here for a description of Agent.__init__ arguments.

​
Agent.call

A method to invoke an agent. 
class Agent:

  @overload
  async def call(self, task: str | template, /, mcp: str | None = None, **scope: Any) -> str: ...

  @overload
  async def call(
      self, return_type: None, task: str | template, /, mcp: str | None = None, **scope: Any
  ) -> None: ...

  @overload
  async def call[T](
    self, return_type: type[T], task: str | template, /, mcp: str | None = None, **scope: Any
  ) -> T: ...
Parameters
​
return_type
type[T] | None
Provide a return type for the agent to have it return an instance of a specific type T.
  • Providing a return type is optional; *if you do not provide a return_type, the return_type will default to str.
  • You may specify a return type of None if you do not care about the result, only the side effects.
​
task
str
required
The agent’s task (or objective) for this invocation of the agent.
If the system argument is provided when spawning the agent, task will be provided as a raw user prompt.
​
mcp
str | None
The string of a path to a .json file representing an MCP configuration. Any servers and/or tools of servers outlined in the config can be used during the agent’s run.
​
command
string
required
The executable command to run the MCP server. This should be an absolute path or a command available in the system PATH.Example:
"python"
​
args
array of string
An array of command-line arguments passed to the server executable. Arguments are passed in order.Example:
["server.py", "--verbose", "--port", "8080"]
​
env
object
An object containing environment variables to set when launching the server. All values must be strings.Example:
{
    "API_KEY": "secret-key",
    "PORT": "8080"
}
​
**scope
dict[str, Any]
Any additional resources added to the agent’s scope for this invocation.
​
Returns
Awaitable[T]
The result the agent returns must be awaited.

​
Agent.total_usage

A method to obtain the token usage of an agent for accross all invocations. 
class Agent:

    def total_usage(self) -> Usage:
​
Returns
Usage
The token usage accross all invocations of the agent.

​
Agent.last_usage

A method to obtain the token usage of an agent for the last invocation. 
class Agent:

    def last_usage(self) -> Usage:
​
Returns
Usage
The token usage of the last invocation of the agent.