SDK API Reference

Full reference for the sec_gemini Python package. All methods are async unless noted.

SecGemini (Client)

from sec_gemini import SecGemini

Method	Description
`SecGemini(api_key, host=...)`	Create a client. `host` defaults to the production API Hub.
`await client.start()`	Connect to the server and authenticate.
`await client.close()`	Close the connection.
`async with SecGemini(...) as client:`	Context manager – calls `start()` / `close()` automatically.

client.sessions

Method	Returns	Description
`await client.sessions.create()`	`Session`	Create a new session
`await client.sessions.list()`	`list[Session]`	List all sessions
`await client.sessions.get(session_id)`	`Session`	Get session by ID (cached)
`await client.sessions.delete(session_id)`	`bool`	Delete a session

client.mcps

Method	Returns	Description
`await client.mcps.list()`	`list[McpServer]`	List account-level MCP servers
`await client.mcps.add(name, uri)`	`McpServer \| None`	Register a new MCP server
`await client.mcps.remove(id)`	`bool`	Remove an MCP server by ID

client.skills

Method	Returns	Description
`await client.skills.list()`	`list[Mcp]`	List all available skills (runtime)
`await client.skills.list_uploaded()`	`list[str]`	List names of user-uploaded skills
`await client.skills.upload(name, content)`	`None`	Upload a skill
`await client.skills.get(name)`	`str`	Get skill content by name
`await client.skills.delete(name)`	`bool`	Delete an uploaded skill

Session

Returned by client.sessions.create() or client.sessions.list().

Properties

Property	Type	Description
`session.id`	`str`	Session ID
`session.name`	`str`	Display name (auto-generated from first prompt)
`session.status`	`str`	Status string (e.g. `"RUNNING"`, `"COMPLETED"`)
`session.status_int`	`int`	Status as protobuf enum integer
`session.created_at`	`float`	Creation timestamp
`session.is_empty`	`bool`	True if no name has been set

Methods

Method	Returns	Description
`await session.prompt(text, meta=None)`	`None`	Send a prompt to start the agent
`await session.cancel()`	`None`	Cancel the running session
`await session.pause()`	`None`	Pause the session
`await session.resume()`	`None`	Resume a paused session
`await session.delete()`	`bool`	Delete the session
`session.add_status_callback(fn)`	`None`	Register `fn(session_id, status)` callback

session.messages

Method	Returns	Description
`async for msg in session.messages.stream()`	`AsyncIterator[dict]`	Stream messages from the server

Each yielded dict contains:

Key	Type	Description
`message_type`	`str`	e.g. `"MESSAGE_TYPE_RESPONSE"`
`content`	`str`	Message text content
`title`	`str`	Short label
`source_type`	`str`	`"SOURCE_TYPE_USER"`, `"SOURCE_TYPE_AGENT"`, `"SOURCE_TYPE_SYSTEM"`
`render_type`	`str`	`"RENDER_TYPE_MARKDOWN"`, `"RENDER_TYPE_JSON"`, etc.
`mime_type`	`str`	Content MIME type
`id`	`str`	Unique message ID
`timestamp`	`str`	ISO timestamp
`snapshot_id`	`str`	Message snapshot ID

session.files

Method	Returns	Description
`await session.files.upload(file_path, content_type="application/octet-stream")`	`None`	Upload a local file
`await session.files.list()`	`list[FileInfo]`	List uploaded files
`await session.files.delete(filename)`	`bool`	Delete a file by name

FileInfo fields: filename, url.

session.mcps

Method	Returns	Description
`await session.mcps.list()`	`list[Mcp]`	List MCPs active in this session
`await session.mcps.set(mcps)`	`bool`	Set active MCPs (list of server URLs)

Mcp fields: name, uri, status, tools (list), skills (list), id.

session.confirmations

Method	Returns	Description
`await session.confirmations.set_config(always_ask)`	`bool`	Set confirmation behavior
`await session.confirmations.get_info()`	`ConfirmationInfo \| None`	Get pending confirmation details
`await session.confirmations.send_tool_confirmation(action_id, confirmed)`	`None`	Approve or deny a tool call

Message Types

Constant	Description
`MESSAGE_TYPE_PROMPT`	User’s input
`MESSAGE_TYPE_RESPONSE`	Agent’s final answer
`MESSAGE_TYPE_THOUGHT`	Agent’s internal reasoning
`MESSAGE_TYPE_PROGRESS`	Transient status update
`MESSAGE_TYPE_TOOL_CALL`	Agent executing a tool
`MESSAGE_TYPE_TOOL_RESULT`	Tool execution output
`MESSAGE_TYPE_TOOL_CONFIRMATION_REQUEST`	Waiting for user approval
`MESSAGE_TYPE_TOOL_CONFIRMATION_RESPONSE`	User’s confirmation decision
`MESSAGE_TYPE_CLARIFICATION_REQUEST`	Agent needs more info
`MESSAGE_TYPE_CLARIFICATION_RESPONSE`	User’s clarification
`MESSAGE_TYPE_TASK_LIST`	Internal task hierarchy dump
`MESSAGE_TYPE_MEMORY_STATE`	Shared context dump
`MESSAGE_TYPE_SESSION_NAME`	Auto-generated session name
`MESSAGE_TYPE_SKILL_LOADED`	Skill loaded notification
`MESSAGE_TYPE_FAILURE`	Agent job failed
`MESSAGE_TYPE_LOG`	Diagnostic log
`MESSAGE_TYPE_DEBUG`	Debug info
`MESSAGE_TYPE_WARNING`	Warning
`MESSAGE_TYPE_ERROR`	Error
`MESSAGE_TYPE_AGENT_RESPONSE`	Agent response (rendered same as RESPONSE)
`MESSAGE_TYPE_NOTIFICATION`	System notification

Job Statuses

Status	Description
`NOT_INITIALIZED`	Session created but not yet started
`PENDING`	Waiting to be scheduled
`RUNNING`	Agent is actively working
`PAUSED`	Session paused by user
`COMPLETED`	Agent finished successfully
`FAILED`	Agent encountered a fatal error
`CANCELED`	Session canceled by user
`WAITING_FOR_TOOL_CONFIRMATION`	Agent paused, waiting for tool approval
`WAITING_FOR_CLARIFICATION`	Agent paused, waiting for user input
`MAX_ATTEMPTS_EXCEEDED`	Agent exceeded maximum retry attempts

Active statuses: RUNNING, PENDING, WAITING_FOR_TOOL_CONFIRMATION, WAITING_FOR_CLARIFICATION

Terminal statuses: COMPLETED, FAILED, CANCELED, MAX_ATTEMPTS_EXCEEDED

Exceptions

from sec_gemini import (
    SdkError,               # Base exception
    AuthenticationError,     # Invalid or expired API key
    ConnectionLostError,     # gRPC connection dropped
    SessionError,            # Session creation/operation failed
    FileOperationError,      # File upload/delete failed
    SkillError,              # Skill upload/get failed
    ProtocolError,           # Unexpected server response
    NotBoundError,           # Operation on unbound object
    ByotError,              # BYOT operation failed
    ByotAuthError,          # BYOT hub authentication failed
    ByotNotAvailableError,  # BYOT dependencies not installed (requires fastmcp)
)

All exceptions inherit from SdkError.