Using the Python SDK

The Python SDK provides an asyncio-native client for managing Sec-Gemini sessions programmatically. All methods are async — wrap with asyncio.run() in synchronous scripts, or use await directly in notebooks.

Run a Workflow

Create a session, send a prompt, and stream the agent’s work:

import asyncio
from sec_gemini import SecGemini

async def main():
    async with SecGemini(api_key="YOUR_API_KEY") as client:
        session = await client.sessions.create()
        await session.prompt("Analyze the email security posture of example.com")

        async for msg in session.messages.stream():
            msg_type = msg.get("message_type", "")
            content = msg.get("content", "")

            if msg_type == "MESSAGE_TYPE_RESPONSE":
                print(f"Agent: {content}")
            elif msg_type == "MESSAGE_TYPE_THOUGHT":
                print(f"  (thinking: {content[:100]})")
            elif msg_type == "MESSAGE_TYPE_TOOL_CALL":
                print(f"  [tool] {msg.get('title', '')}")

asyncio.run(main())

Check and Resume a Workflow

Sessions persist server-side. If your client disconnects, the agent keeps working. Reconnect to check status or resume streaming:

async with SecGemini(api_key="YOUR_API_KEY") as client:
    # List all sessions
    sessions = await client.sessions.list()
    for s in sessions:
        print(f"{s.id[:12]}  {s.name:<30}  {s.status}")

    # Resume streaming from an existing session
    session = await client.sessions.get("your-session-id")
    async for msg in session.messages.stream():
        print(msg.get("content", ""))

You can also pause, resume, or cancel:

await session.pause()
await session.resume()
await session.cancel()

Attach Files

Upload files for the agent to reference during a session:

await session.files.upload("/path/to/report.pdf")

files = await session.files.list()
for f in files:
    print(f.filename)

await session.files.delete("report.pdf")

The agent works best with text-based formats (TXT, JSON, CSV, YAML, XML, logs, source code). PDFs are supported with automatic text extraction. Files expire after 7 days.

Add Your Own Tools

Use BYOT to give the agent access to tools on your machine. Start the BYOT client in a separate terminal:

sec-gemini-byot --use-baseline-tools

To add custom tools, write a FastMCP server and pass it:

sec-gemini-byot --use-baseline-tools --additional-mcps ./my_tools.py

Your SDK script stays the same — the agent can now call local and custom tools alongside cloud tools.

Add Skills

Skills are markdown instructions that teach the agent specific workflows:

await client.skills.upload(
    name="vuln-triage.md",
    content="""---
name: vuln-triage
description: Triage and prioritize CVEs
---
When given CVEs, prioritize by exploitability,
check for patches, and present a ranked table.
"""
)

Handle Errors

All exceptions inherit from SdkError:

from sec_gemini import SecGemini, SdkError, ConnectionLostError

try:
    async with SecGemini(api_key="YOUR_API_KEY") as client:
        session = await client.sessions.create()
        await session.prompt("Analyze example.com")
        async for msg in session.messages.stream():
            print(msg.get("content", ""))
except ConnectionLostError:
    print("Connection lost -- reconnect and stream again to resume.")
except SdkError as e:
    print(f"SDK error: {e}")

See the SDK API Reference for the complete API surface, message types, and exception hierarchy.