> ## 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.

# Loggers

### `AgentLogger`

{/* START */}

A pluggable base class that powers listeners by defining the logging behaviour itself.
Subclass this and implement the abstract methods to create a custom logger.
Can be used as a context manager to set a contextual logger for the current scope.

{/* @signature AgentLogger customer_sdk/python/src/agentica/logging/agent_logger.py style=abstract wrap */}

```python wrap theme={null}
class AgentLogger(ABC):

    local_id: LogId | None
    parent_local_id: LogId | None

    @abstractmethod
    def on_spawn(self) -> None:
        ...

    @abstractmethod
    def on_call_enter(self, user_prompt: str, parent_local_id: LogId | None = None) -> None:
        ...

    @abstractmethod
    def on_call_exit(self, result: object) -> None:
        ...

    @abstractmethod
    async def on_chunk(self, chunk: Chunk) -> None:
        ...
```

**Parameters**

{/* START */}

<ParamField body="local_id" type="LogId | None">
  The local identifier for this logger instance.
</ParamField>

<ParamField body="parent_local_id" type="LogId | None">
  The local identifier of the parent logger, if any.
</ParamField>

#### `on_spawn`

{/* START */}

Called when an agent is spawned.
Implementations should initialise any logging state needed for a new agent.

{/* @signature AgentLogger.on_spawn customer_sdk/python/src/agentica/logging/agent_logger.py */}

```python theme={null}
def on_spawn(self) -> None:
    ...
```

#### `on_call_enter`

{/* START */}

Called when an agent receives a prompt.

{/* @signature AgentLogger.on_call_enter customer_sdk/python/src/agentica/logging/agent_logger.py */}

```python theme={null}
def on_call_enter(self, user_prompt: str, parent_local_id: LogId | None = None) -> None:
    ...
```

**Parameters**

{/* START */}

<ParamField body="user_prompt" type="str">
  The task or prompt provided to the agent for this invocation.
</ParamField>

<ParamField body="parent_local_id" type="LogId | None">
  The local identifier of the parent invocation, if this is a nested call.
</ParamField>

#### `on_call_exit`

{/* START */}

Called when an agent returns a result.

{/* @signature AgentLogger.on_call_exit customer_sdk/python/src/agentica/logging/agent_logger.py */}

```python theme={null}
def on_call_exit(self, result: object) -> None:
    ...
```

**Parameters**

{/* START */}

<ParamField body="result" type="object">
  The result returned by the agent invocation.
</ParamField>

#### `on_chunk`

{/* START */}

Called when a streaming chunk is received.

{/* @signature AgentLogger.on_chunk customer_sdk/python/src/agentica/logging/agent_logger.py */}

```python theme={null}
async def on_chunk(self, chunk: Chunk) -> None:
    ...
```

**Parameters**

{/* START */}

<ParamField body="chunk" type="Chunk">
  A single piece of streamed content from an agent invocation.
</ParamField>

### `Chunk`

{/* START */}

A single piece of streamed content from an agent invocation.

{/* @signature Chunk customer_sdk/python/src/agentica/common.py style=dataclass */}

```python theme={null}
@dataclass
class Chunk:

    role: Role
    content: str
    type: str | None = None  # 'reasoning', 'output_text', 'code', etc.
```

**Parameters**

{/* START */}

<ParamField body="role" type="Role">
  The role of the message sender ('agent', 'user', or 'system').
</ParamField>

<ParamField body="content" type="str">
  The text content of the chunk.
</ParamField>

<ParamField body="type" type="str | None">
  The kind of streamed content:

  * 'reasoning' — internal reasoning / chain-of-thought
  * 'output\_text' — final output text
  * 'code' — code being executed in the REPL
  * 'usage' — token usage statistics
  * 'invocation\_exit' — signals the end of an invocation
  * None — untyped chunk
</ParamField>