Skip to main content
Agents are stateful, long‑lived LLM workers you spawn and call repeatedly; they keep conversational history across invocations. We expose two ways to instantiate an agent:
  • direct instantiation via Agent.__init__
  • awaitable instantiation via the spawn function Both return an instance of the Agent class.
Direct instantiation is often useful in functions that must be synchronous e.g. setting attributes of objects in protected methods such as __init__.

​
spawn

async def spawn(
    premise: str | None = None,
    scope: dict[str, Any] | None = None, *,
    system: str | None = None,
    mcp: str | None = None,
    model:  Literal[
        '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',
    ] = 'openai:gpt-4.1',
    max_tokens: int = 2048,
    listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
) -> 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.
​
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.
​
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
Defaults to openai:gpt-4.1.
​
max_tokens
int
The maximum number of tokens that the agent can generate during one round of inference.Defaults to 2048.
​
listener
AgentListener | None
An optional listener for logging the agent’s activity and chat history. If the global default listener is enabled, and this is set to None, the default listener will be used.

​
Agent

The Agent class represents a stateful agent that maintains conversation history.

​
__init__

class Agent:

  def __init__(
    premise: str | None = None,
    scope: dict[str, Any] | None = None, *,
    system: str | None = None,
    mcp: str | None = None,
    model:  Literal[
        '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',
    ] = 'openai:gpt-4.1',
    max_tokens: int = 2048,
    listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
  )
Parameters See agentica.spawn(...) for a description of Agent.__init__ arguments.

​
call

Invoke the agent with a task. 
class Agent:

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

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

  @overload
  async def call[T](
    self, return_type: type[T], task: str, /, 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.
​
**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.