log()

Use agent.log() to communicate with your users and debug your agent. Every message appears in your terminal, and by default also shows up in the Circuit UI for your users to see. Pass debug=True to skip sending the message to the user.

Signature

agent.log(
    message: str | dict | list,
    error: bool = False,
    debug: bool = False
) -> LogResponse

Parameters

Param	Type	Description
message	str | dict | list	Content to log (can be str, dict, list or SDK response objects)
error?	bool	Mark this log entry as an error (logs to stderr and sends as error type)
debug?	bool	Skip sending to Circuit UI (console only)

Returns

• LogResponse

class LogResponse:
    success: bool
    error: str | None       # Error message (only present on failure)
    error_details: dict | None  # Detailed error info (only present on failure)

Examples

# Standard log: Shows to user in Circuit UI and console
agent.log("Starting execution")

# Log a dictionary: Pretty-printed in console and serialized/truncated for BE
agent.log({
    "wallet": agent.sessionWalletAddress,
    "balance": "1.5 ETH",
    "status": "active"
})

# Log a list: Pretty-printed in console and serialized/truncated for BE
agent.log([{"position": 1}, {"position": 2}])

# Log a Pydantic model (from SDK response)
result = agent.memory.get("key")
agent.log(result) # Pretty-printed in console and serialized/truncated for BE

# Error log: Shows to user in Circuit UI as an error
agent.log("Transaction failed", error=True)

# Debug log: Only you see this in your terminal
agent.log("Internal state: processing...", debug=True)

Logging Behavior

Code	You see	User sees
agent.log("msg")	✅ in terminal	✅ in Circuit UI
agent.log("msg", error=True )	✅ as error in terminal	✅ as error in UI
agent.log("msg", debug=True )	✅ in terminal	❌ hidden from user
agent.log("msg", error=True, debug=True )	✅ as error in terminal	❌ hidden from user