> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symbolica.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

### `spawn`

{/* START */}

Spawn a new agent.

{/* @signature spawn customer_sdk/python/src/agentica/agent.py */}

```python theme={null}
async def spawn(
    premise: str | None = None,
    scope: dict[str, Any] | None = None,
    *,
    system: str | None = None,
    mcp: str | None = None,
    model: ModelId = DEFAULT_AGENT_MODEL,
    listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
    max_tokens: int | MaxTokens = MaxTokens.default(),
    reasoning_effort: ReasoningEffort | None = None,
    cache_ttl: CacheTTL | None = None,
) -> Agent:
    ...
```

**Parameters**

{/* START */}

<ParamField body="premise" type="str or 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.
</ParamField>

<ParamField body="scope" type="dict[str, Any]">
  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.
</ParamField>

<ParamField body="system" type="str or 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.
</ParamField>

<ParamField body="mcp" type="str or 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 execution of the agent.
</ParamField>

<ParamField body="model" type="str">
  The model which backs your agent.
  Any OpenRouter model slug is supported.
</ParamField>

<ParamField body="listener" type="Callable[[], AgentListener] | None">
  Optional listener constructor for logging the agent's activity and chat history.
  If None, no listener will be used.
</ParamField>

<ParamField body="max_tokens" type="int | MaxTokens">
  When an integer is supplied, this is the maximum number of tokens for an invocation.
  For more fine-grained control, a `MaxTokens` object may be passed.
</ParamField>

<ParamField body="reasoning_effort" type="'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | None">
  Constrains thinking budget on reasoning models which support it (gpt 5.2, sonnet 4.5, gemini 3, etc...)
  Higher values use more reasoning tokens but may produce better results.
  If None, uses the model's default reasoning effort.
</ParamField>

<ParamField body="cache_ttl" type="'5m' | '1h' | None">
  Controls how long Anthropic prompt caching entries persist.
  Only used for Anthropic models; ignored for other providers.
  '5m' is the default Anthropic cache duration. '1h' costs more but caches longer.
  If None, uses the default ephemeral cache (5 minutes).
</ParamField>

<Warning>
  The `system` argument cannot be provided along with the `premise` argument, and vice versa. `premise` will **not** be formatted if using [`template`](/references/python/templating#template).
</Warning>

<Accordion title="MCP Configuration Fields">
  <ParamField path="command" type="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"
    ```
  </ParamField>

  <ParamField path="args" type="array of string">
    An array of command-line arguments passed to the server executable. Arguments are passed in order.

    Example:

    ```json theme={null}
    ["server.py", "--verbose", "--port", "8080"]
    ```
  </ParamField>

  <ParamField path="env" type="object">
    An object containing environment variables to set when launching the server. All values must be strings.

    Example:

    ```json theme={null}
    {
        "API_KEY": "secret-key",
        "PORT": "8080"
    }
    ```
  </ParamField>
</Accordion>

<Note>
  The default model is `openai/gpt-4.1`.
</Note>

<Note>
  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 hierarchy, see [here](/concepts/logging_and_streaming/python).
</Note>

{/* START */}

<ResponseField name="Returns" type="Agent">
  An agent object.
</ResponseField>

### `Agent.__init__`

{/* START */}

Directly instantiate an agent.

{/* @signature Agent.__init__ customer_sdk/python/src/agentica/agent.py context=class */}

```python theme={null}
class Agent:

    def __init__(
        self,
        premise: str | None = None,
        scope: dict[str, Any] | bytes | None = None,
        *,
        system: str | None = None,
        mcp: str | None = None,
        model: ModelId = DEFAULT_AGENT_MODEL,
        listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
        max_tokens: int | MaxTokens = MaxTokens.default(),
        reasoning_effort: ReasoningEffort | None = None,
        cache_ttl: CacheTTL | None = None,
    ):
        ...
```

**Parameters**

See [here](/references/python/agents#spawn) for a description of `Agent.__init__` arguments.

### `Agent.call`

{/* START */}

Invokes an agent with arbitrary return type.

{/* @signature Agent.call customer_sdk/python/src/agentica/agent.py context=class overloads wrap */}

```python wrap theme={null}
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**

{/* START */}

<ParamField body="return_type" type="type[T]">
  Provide a return type for the agent to have it return an instance of a specific type `T`.
</ParamField>

<ParamField body="task" type="str">
  The agent's task (or objective) for this invocation of the agent.
</ParamField>

<ParamField body="mcp" type="str or 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.
</ParamField>

<ParamField body="scope" type="dict[str, Any]">
  Any additional resources added to the agent's scope for this invocation.
</ParamField>

<Info>
  * 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.
</Info>

<Info>
  If the `system` argument is provided when spawning the agent, `task` will be provided as a raw user prompt.
</Info>

<Accordion title="MCP Configuration Fields">
  <ParamField path="command" type="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"
    ```
  </ParamField>

  <ParamField path="args" type="array of string">
    An array of command-line arguments passed to the server executable. Arguments are passed in order.

    Example:

    ```json theme={null}
    ["server.py", "--verbose", "--port", "8080"]
    ```
  </ParamField>

  <ParamField path="env" type="object">
    An object containing environment variables to set when launching the server. All values must be strings.

    Example:

    ```json theme={null}
    {
        "API_KEY": "secret-key",
        "PORT": "8080"
    }
    ```
  </ParamField>
</Accordion>

{/* START */}

<ResponseField name="Returns" type="Awaitable[T]">
  An awaitable result of type `T` which the agent returns.
</ResponseField>

### `Agent.total_usage`

{/* START */}

Get the total usage across all invocations.

{/* @signature Agent.total_usage customer_sdk/python/src/agentica/agent.py context=class */}

```python theme={null}
class Agent:

    def total_usage(self) -> ResponseUsage:
        ...
```

{/* @returns Agent.total_usage customer_sdk/python/src/agentica/agent.py */}

### `Agent.last_usage`

{/* START */}

Get the usage for the last invocation.

{/* @signature Agent.last_usage customer_sdk/python/src/agentica/agent.py context=class */}

```python theme={null}
class Agent:

    def last_usage(self) -> ResponseUsage:
        ...
```

{/* @returns Agent.last_usage customer_sdk/python/src/agentica/agent.py */}