Agent

serveAgent(handler: AgentHandler, capability: Omit<AgentCapability, 'enabled'> = {}): void

def serve_agent(self, handler: AgentHandler, capability: AgentCapability | None = None) -> None

func (c *Client) ServeAgent(handler AgentHandler, capability AgentCapability)

export interface AgentHandler {
  /**
   * Decides whether to accept a turn.start and reports the configuration the
   * agent will apply. It runs before turn.start is answered, so it must not
   * do the turn's work. A thrown RpcError keeps its code.
   */
  openTurn(params: TurnStartParams): Promise<TurnStartResult>
  /**
   * Does the turn's work. signal is aborted by turn.cancel, session.close and
   * deadline_ms. Resolving ends the turn as completed, an aborted signal as
   * canceled (failed for deadline_ms), a rejection as failed (the SDK emits
   * session.error first).
   */
  runTurn(turn: AgentTurn, signal: AbortSignal): Promise<void>
  /** Releases the local conversation after session.close. */
  closeSession(sessionId: string, reason: string): Promise<void>
}

class AgentHandler(Protocol):
    async def open_turn(self, params: TurnStartParams) -> TurnStartResult: ...
    async def run_turn(self, turn: AgentTurn) -> None: ...
    async def close_session(self, session_id: str, reason: str) -> None: ...

type AgentHandler interface {
	// OpenTurn decides whether to accept a turn.start and reports the
	// configuration the agent will actually apply. It runs before turn.start
	// is answered, so it must not do the turn's work. An *RPCError keeps its
	// code (for example -32001 for a cwd outside the allowed roots).
	OpenTurn(ctx context.Context, params TurnStartParams) (TurnStartResult, error)
	// RunTurn does the turn's work and returns when the turn is over. ctx is
	// canceled by turn.cancel and session.close. A nil error ends the turn as
	// completed, a canceled ctx as canceled, any other error as failed (the
	// SDK emits session.error first).
	RunTurn(ctx context.Context, turn *AgentTurn) error
	// CloseSession releases the local conversation after session.close.
	CloseSession(ctx context.Context, sessionID, reason string) error
}

get sessionId(): string

get turnId(): string

@property
def session_id(self) -> str

@property
def turn_id(self) -> str

func (t *AgentTurn) SessionID() string

func (t *AgentTurn) TurnID() string

func (t *AgentTurn) Params() TurnStartParams

get inputs(): AsyncIterable<TurnInputParams> &

# Python: `turn.inputs` is an `asyncio.Queue[TurnInputParams]` attribute of `AgentTurn`.

func (t *AgentTurn) Inputs() <-chan TurnInputParams

emit(event: AgentEvent): string

emitWithId(eventId: string, event: AgentEvent): string

newEventId(): string

def emit(self, event: Any) -> str

def emit_with_id(self, event_id: str, event: Any) -> str

def new_event_id(self) -> str

func (t *AgentTurn) Emit(event any) (string, error)

func (t *AgentTurn) EmitWithID(eventID string, event any) (string, error)

func (t *AgentTurn) NewEventID() string

delta(eventId: string, eventType: EventDeltaType, index: number, text: string): void

async def delta(self, event_id: str, event_type: str, index: int, text: str) -> None

func (t *AgentTurn) Delta(eventID, eventType string, index int64, text string)

flush(signal?: AbortSignal): Promise<void>

async def flush(self) -> None

func (t *AgentTurn) Flush(ctx context.Context) error

async requestInteraction(
  request: Omit<InteractionRequestParams, 'session_id' | 'turn_id' | 'interaction_id'> & { interaction_id?: string },
  signal?: AbortSignal,
): Promise<InteractionResponseParams>

async def request_interaction(self, params: InteractionRequestParams) -> InteractionResponseParams

func (t *AgentTurn) RequestInteraction(ctx context.Context, params InteractionRequestParams) (InteractionResponseParams, error)

cancelInteraction(interactionId: string, reason: InteractionCancelReason): Promise<void>

async def cancel_interaction(self, interaction_id: str, reason: str) -> None

func (t *AgentTurn) CancelInteraction(interactionID, reason string)

async requestCustomTool(
  name: string,
  input: Record<string, unknown>,
  signal?: AbortSignal,
): Promise<{ toolUseId: string; result: AgentCustomToolResultParams }>

async def request_custom_tool(self, name: str, tool_input: dict[str, Any]) -> tuple[str, AgentCustomToolResultParams]

func (t *AgentTurn) RequestCustomTool(ctx context.Context, name string, input map[string]any) (string, AgentCustomToolResultParams, error)

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (t *AgentTurn) RefreshModelToken(ctx context.Context) (ModelTokenRefreshResult, error)

get agentCapability(): AgentCapability | undefined

def agent_capability(self) -> AgentCapability | None

func (e *Executor) AgentCapability() (*AgentCapability, error)

async startTurn(params: TurnStartParams): Promise<TurnStartResult>

async def start_turn(self, params: TurnStartParams) -> TurnStartResult

func (e *Executor) StartTurn(ctx context.Context, params TurnStartParams) (TurnStartResult, error)

sendTurnInput(params: TurnInputParams): Promise<Ack>

async def send_turn_input(self, params: TurnInputParams) -> Ack

func (e *Executor) SendTurnInput(ctx context.Context, params TurnInputParams) (Ack, error)

cancelTurn(params: TurnCancelParams): Promise<TurnCancelResult>

async def cancel_turn(self, params: TurnCancelParams) -> TurnCancelResult

func (e *Executor) CancelTurn(ctx context.Context, params TurnCancelParams) (TurnCancelResult, error)

respondInteraction(params: InteractionResponseParams): Promise<InteractionResponseResult>

async def respond_interaction(self, params: InteractionResponseParams) -> InteractionResponseResult

func (e *Executor) RespondInteraction(ctx context.Context, params InteractionResponseParams) (InteractionResponseResult, error)

respondCustomToolResult(params: AgentCustomToolResultParams): Promise<CustomToolResultResult>

async def respond_custom_tool_result(self, params: AgentCustomToolResultParams) -> CustomToolResultResult

func (e *Executor) RespondCustomToolResult(ctx context.Context, params AgentCustomToolResultParams) (CustomToolResultResult, error)

closeAgentSession(params: SessionCloseParams): Promise<SessionCloseResult>

async def close_agent_session(self, params: SessionCloseParams) -> SessionCloseResult

func (e *Executor) CloseAgentSession(ctx context.Context, params SessionCloseParams) (SessionCloseResult, error)

export interface AgentPlatform {
  /** Highest contiguous sequence already persisted for the session (0 when none). Asked once per session. */
  ackedSequence(sessionId: string): Promise<number>
  /** Persists one durable event; resolves once durable. Called once per event, in sequence order per session. */
  agentEvent(executor: HarnessExecutor, event: AgentEventRecord): Promise<void>
  /** Relays a transient preview. Never persisted. */
  agentDelta(executor: HarnessExecutor, delta: SessionEventDeltaParams): void
  /** Opens (or for a repeated interaction_id returns) the platform interaction; returns its id. */
  interactionRequested(executor: HarnessExecutor, request: InteractionRequestParams): Promise<string>
  /** Closes the platform interaction without an answer. */
  interactionCanceled(executor: HarnessExecutor, cancel: InteractionCancelParams): Promise<void>
}

class AgentPlatform(Protocol):
    """Where durable agent events, previews and interactions go."""
    async def acked_sequence(self, session_id: str) -> int: ...
    async def agent_event(self, executor: Executor | None, record: AgentEventRecord) -> None: ...
    def agent_delta(self, executor: Executor, delta: SessionEventDeltaParams) -> None: ...
    async def interaction_requested(self, executor: Executor, request: InteractionRequestParams) -> str: ...
    async def interaction_canceled(self, executor: Executor, cancel: InteractionCancelParams) -> None: ...

type AgentPlatform interface {
	// AckedSequence is the highest contiguous sequence already persisted for
	// the session (0 when none). The harness asks once per session per process
	// so a restarted platform keeps deduplicating resent events.
	AckedSequence(ctx context.Context, sessionID string) (int64, error)
	// AgentEvent persists one durable event and returns once it is durable;
	// only then is it acknowledged to the executor and may be published to
	// clients. It is called once per event, in sequence order per session.
	AgentEvent(ctx context.Context, executor *Executor, event AgentEventRecord) error
	// AgentDelta relays a transient preview (Anthropic event_start /
	// event_delta). Never persisted.
	AgentDelta(executor *Executor, delta SessionEventDeltaParams)
	// InteractionRequested opens (or, for a repeated interaction_id, returns)
	// the platform interaction and returns its id. Answer it later with
	// Executor.RespondInteraction.
	InteractionRequested(ctx context.Context, executor *Executor, request InteractionRequestParams) (string, error)
	// InteractionCanceled closes the platform interaction without an answer.
	InteractionCanceled(ctx context.Context, executor *Executor, cancel InteractionCancelParams) error
}