Approvals and sign-ins

How a program answers the approvals and the connector sign-ins of a turn: the handler, the request it gets, the answers, and what turn.answer returns.

Guide: Approvals.

class ApprovalHandler(Protocol):
    def __call__(
        ctx: ApprovalCallbackContext,
        request: ApprovalRequest,
        /,
    ) -> AllowApproval | DenyApproval | KeepCallbackOpen | Awaitable[AllowApproval | DenyApproval | KeepCallbackOpen]

class ApprovalHandler(Protocol):
    def __call__(
        ctx: ApprovalCallbackContext,
        request: ApprovalRequest,
        /,
    ) -> AllowApproval | DenyApproval | KeepCallbackOpen | Awaitable[AllowApproval | DenyApproval | KeepCallbackOpen]

A plain or async function of (ctx, request) that answers an approval: AllowApproval, DenyApproval, or KeepCallbackOpen() to keep it open. Any other return, None included, raises SdkError. Its parameters may have any names.

• It runs in your program, and only while agent.run(), session.run() or turn.result() waits. Between those calls, an approval stays open. iter_events() never runs it.
• A plain function runs on the event loop: do not block in it. An async def function can await.
• If it raises, or returns something else, the waiting call raises that error and the approval stays open. The turn keeps running.
• It also answers the approvals of the session's subagents, with ctx.session set to the subagent's session.
• Decide on request.tool.id, the tool's stable ID, never on the name the model called.
• AllowApproval(scope="session") also allows the same call with the same input for the rest of the session.

class ApprovalRequest(
    *,
    tool: ApprovalTool,
    hook: str | None = None,
    title: str,
    input: JsonValue = None,
)

class ApprovalRequest(
    *,
    tool: ApprovalTool,
    hook: str | None = None,
    title: str,
    input: JsonValue = None,
)

A tool call that waits for an approval. The IDs are in the handler's ctx.

A hook's approval cannot be allowed for the session. Answer it with AllowApproval(), once.

class ApprovalTool(
    *,
    id: str,
    name: str,
    kind: Literal['builtin', 'client', 'mcp', 'connector', 'plugin'] | UnknownValue,
    description: str | None = None,
    input_schema: dict[str, JsonValue] | None = None,
    output_schema: dict[str, JsonValue] | None = None,
    definition: PythonTool[..., Any] | ClientTool[..., Any] | ToolDefinition | None = None,
    annotations: ToolAnnotations = ToolAnnotations(),
)

class ApprovalTool(
    *,
    id: str,
    name: str,
    kind: Literal['builtin', 'client', 'mcp', 'connector', 'plugin'] | UnknownValue,
    description: str | None = None,
    input_schema: dict[str, JsonValue] | None = None,
    output_schema: dict[str, JsonValue] | None = None,
    definition: PythonTool[..., Any] | ClientTool[..., Any] | ToolDefinition | None = None,
    annotations: ToolAnnotations = ToolAnnotations(),
)

The tool that an approval is for.

Decide on id, never on name: name changes with how the model called the tool. A hint the tool does not declare in annotations takes MCP's default, which assumes the worst.

class AllowApproval(*, scope: Literal['once', 'session'] = 'once')

class AllowApproval(*, scope: Literal['once', 'session'] = 'once')

Allow this call once, or matching calls for the rest of the session.

class DenyApproval()

class DenyApproval()

Deny this call.

class KeepCallbackOpen()

class KeepCallbackOpen()

What a callback handler returns to keep the callback open, for someone to answer later.

Return agents.KeepCallbackOpen() from on_approval, on_client_tool or a client tool's answer: nothing is sent, the callback stays open, and the waiting call returns Blocked on it, unless it was given after= a Blocked that already lists the callback: that wait returns only on a later change. Answer it later with turn.answer, an approval with AllowApproval or DenyApproval and a client tool call with the tool's result, or answer it from another client.

It is a handler's return only, never an answer: turn.answer refuses it. None is not this either: an approval handler that returns None raises agents.SdkError, and a client tool that returns None sends the null result.

class SignInRequest(
    *,
    source: Literal['connector', 'mcp'] | UnknownValue,
    id: str,
    name: str,
    mode: Literal['connect', 'reconnect'] | UnknownValue = 'connect',
)

class SignInRequest(
    *,
    source: Literal['connector', 'mcp'] | UnknownValue,
    id: str,
    name: str,
    mode: Literal['connect', 'reconnect'] | UnknownValue = 'connect',
)

One source that a sign-in asks the user to connect.

class SignInAnswer(*, connected: Iterable[str] = (), denied: Iterable[str] = ())

class SignInAnswer(*, connected: Iterable[str] = (), denied: Iterable[str] = ())

The answer to an OpenSignIn: the IDs of the sources the user connected, and of those they refused to connect.

Name each source the sign-in asks for in one list: an answer that leaves one out raises SdkError and sends nothing, and the sign-in stays open. The agent checks each source said to be connected, and is told when one is still not connected.

class Answered(
    *,
    session_id: str,
    callback_id: str,
    answer: AllowApproval | DenyApproval | None = None,
)

class Answered(
    *,
    session_id: str,
    callback_id: str,
    answer: AllowApproval | DenyApproval | None = None,
)

The callback was open when read, and it was answered.

class AlreadySettled(*, session_id: str, callback_id: str)

class AlreadySettled(*, session_id: str, callback_id: str)

An answer named a callback that is no longer open: it was answered, or it closed. Nothing changed.

Another client may have answered first, the callback's turn ended, or the session ended.

class NotFound(*, session_id: str, callback_id: str)

class NotFound(*, session_id: str, callback_id: str)

An answer named a callback that the session never opened, and that none of its subagents has open. Nothing changed.

Once a subagent's callback is no longer open, its root says NotFound. The subagent's own session says AlreadySettled.