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: string | object | any[], 
  options?: {
    error?: boolean;
    debug?: boolean;
  }
): Promise<LogResponse>

Parameters

Param	Type	Description
message	string | object | any[]	Content to log
options?	{ error?: boolean; debug?: boolean }	Optional logging flags

Returns

• Promise<LogResponse>

interface LogResponse {
  success: boolean;
  error?: string; // Error message (only present on failure)
  errorMessage?: string; // Detailed error info (only present on failure)
  errorDetails?: object; // Detailed error info (only present on failure)
}

Examples

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

// Log an object: Pretty-printed to console and serialized/truncated for BE
await agent.log({ positions: agent.currentPositions });

// Error log: Shows to user in Circuit UI as an error
await agent.log(`Transaction failed: ${result.error}`, { error: true });

// Debug log: Only you see this in your terminal
await agent.log("Debug info", { debug: true });

// Check log: Confirm message reached user
const logResult = await agent.log("Important message");
if (!logResult.success) {
  // Rare, usually means Circuit UI is unreachable
}

Logging Behavior

Code	You see	User sees
agent.log("msg")	✅ in terminal	✅ in Circuit UI
agent.log("msg", { error: true })	✅ as error in term	✅ as error in UI
agent.log("msg", { debug: true })	✅ in terminal	❌ hidden from user
agent.log("msg", { error: true, debug: true })	✅ as error in term	❌ hidden from user