Loggers

`AgentLogger`

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.

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

LogId | None

The local identifier for this logger instance.

LogId | None

The local identifier of the parent logger, if any.

`on_spawn`

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

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

`on_call_enter`

Called when an agent receives a prompt.

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

Parameters

str

The task or prompt provided to the agent for this invocation.

LogId | None

The local identifier of the parent invocation, if this is a nested call.

`on_call_exit`

Called when an agent returns a result.

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

Parameters

object

The result returned by the agent invocation.

`on_chunk`

Called when a streaming chunk is received.

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

Parameters

Chunk

A single piece of streamed content from an agent invocation.

`Chunk`

A single piece of streamed content from an agent invocation.

@dataclass
class Chunk:

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

Parameters

Role

The role of the message sender (‘agent’, ‘user’, or ‘system’).

str

The text content of the chunk.

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

Core

Logging

Prompting

`AgentLogger`

`on_spawn`

`on_call_enter`

`on_call_exit`

`on_chunk`

`Chunk`

​AgentLogger

​on_spawn

​on_call_enter

​on_call_exit

​on_chunk

​Chunk

`AgentLogger`

`on_spawn`

`on_call_enter`

`on_call_exit`

`on_chunk`

`Chunk`