Python SDK Reference

Complete API reference for the Kortix Python SDK

Kortix Client

The main entry point for the SDK.

Kortix

from kortix import kortix

client = kortix.Kortix(api_key: str, api_url: str = "https://api.kortix.com/v1")

api_key · string · required

Your Kortix API key from settings/api-keys

api_url · string · default: "https://api.kortix.com/v1"

The API base URL. Override for local development or custom deployments.

Properties:

• client.Agent: Agent management interface
• client.Thread: Thread management interface

---

Agent Management

Create and manage AI agents.

Agent.create()

Create a new agent with specified configuration.

agent = await client.Agent.create(
    name: str,
    system_prompt: str,
    mcp_tools: list[KortixTools] = [],
    allowed_tools: list[str] | None = None
) -> Agent

name · string · required

A friendly name for the agent

system_prompt · string · required

Instructions that define the agent’s behavior and personality

mcp_tools · list[KortixTools] · default: "[]"

List of tools (MCPTools or AgentPressTools) the agent can use

allowed_tools · list[str] | None · default: "None"

Specific tool names to enable. If None, all tools are enabled.

Returns: Agent instance

Example:

agent = await client.Agent.create(
    name="Research Assistant",
    system_prompt="You are a research assistant that helps find and summarize information.",
    mcp_tools=[kortix.AgentPressTools.WEB_SEARCH_TOOL],
    allowed_tools=["web_search_tool"]
)

Agent.get()

Retrieve an existing agent by ID.

agent = await client.Agent.get(agent_id: str) -> Agent

agent_id · string · required

The unique identifier of the agent

Returns: Agent instance

Example:

agent = await client.Agent.get("agent_abc123")

---

Agent Instance

An Agent instance provides methods to interact with a specific agent.

agent.run()

Execute the agent with a prompt on a thread.

run = await agent.run(
    prompt: str,
    thread: Thread,
    model: str | None = None
) -> AgentRun

prompt · string · required

The user message/prompt to send to the agent

thread · Thread · required

The thread context for the conversation

model · string · default: "anthropic/claude-sonnet-4-20250514"

Override the model for this specific run

Returns: AgentRun instance

Example:

thread = await client.Thread.create()
run = await agent.run("What's the weather like?", thread)

agent.update()

Update agent configuration.

await agent.update(
    name: str | None = None,
    system_prompt: str | None = None,
    mcp_tools: list[KortixTools] | None = None,
    allowed_tools: list[str] | None = None
)

name · string

New name for the agent

system_prompt · string

New system prompt

mcp_tools · list[KortixTools]

New list of tools

allowed_tools · list[str]

New list of allowed tool names

Example:

await agent.update(
    system_prompt="You are now a coding assistant.",
    allowed_tools=["sb_files_tool", "sb_shell_tool"]
)

agent.details()

Get detailed information about the agent.

details = await agent.details() -> AgentResponse

Returns: AgentResponse with complete agent configuration

---

Thread Management

Create and manage conversation threads.

Thread.create()

Create a new conversation thread.

thread = await client.Thread.create(name: str | None = None) -> Thread

name · string

Optional name for the thread/project

Returns: Thread instance

Example:

thread = await client.Thread.create(name="Customer Support Chat")

Thread.get()

Retrieve an existing thread by ID.

thread = await client.Thread.get(thread_id: str) -> Thread

thread_id · string · required

The unique identifier of the thread

Returns: Thread instance

Thread.delete()

Delete a thread.

await client.Thread.delete(thread_id: str)

thread_id · string · required

The unique identifier of the thread to delete

---

Thread Instance

A Thread instance provides methods to interact with a specific thread.

thread.add_message()

Add a message to the thread.

message_id = await thread.add_message(message: str) -> str

message · string · required

The message content to add

Returns: Message ID (string)

Example:

message_id = await thread.add_message("Hello, agent!")

thread.del_message()

Delete a message from the thread.

await thread.del_message(message_id: str)

message_id · string · required

The ID of the message to delete

thread.get_messages()

Retrieve all messages in the thread.

messages = await thread.get_messages() -> list[Message]

Returns: List of Message objects

Example:

messages = await thread.get_messages()
for msg in messages:
    print(f"{msg.type}: {msg.content}")

thread.get_agent_runs()

Get all agent runs for this thread.

runs = await thread.get_agent_runs() -> list[AgentRun] | None

Returns: List of AgentRun objects or None if no runs exist

---

Agent Run

Represents an execution of an agent.

run.get_stream()

Get a stream of the agent’s response.

stream = await run.get_stream() -> AsyncGenerator[str, None]

Returns: Async generator yielding response chunks

Example:

stream = await run.get_stream()
async for chunk in stream:
    print(chunk, end="")

---

Tools

MCPTools

Connect to custom MCP (Model Context Protocol) servers.

from kortix import kortix

mcp_tools = kortix.MCPTools(
    endpoint: str,
    name: str,
    allowed_tools: list[str] | None = None
)
await mcp_tools.initialize()

endpoint · string · required

The HTTP URL of the MCP server (e.g., “http://localhost:4000/mcp/”)

name · string · required

A friendly name for this MCP server

allowed_tools · list[str]

Specific tool names to enable from this server

Properties:

• url: The MCP server endpoint
• name: The server name
• type: Always “http”
• enabled_tools: List of enabled tool names

Example:

mcp_tools = kortix.MCPTools(
    "http://localhost:4000/mcp/",
    "Weather Service",
    allowed_tools=["get_weather", "get_forecast"]
)
await mcp_tools.initialize()

agent = await client.Agent.create(
    name="Weather Agent",
    system_prompt="You provide weather information.",
    mcp_tools=[mcp_tools]
)

AgentPressTools

Built-in tools provided by Kortix.

from kortix import kortix

# Available tools:
kortix.AgentPressTools.SB_FILES_TOOL        # Read, write, and edit files
kortix.AgentPressTools.SB_SHELL_TOOL        # Execute shell commands
kortix.AgentPressTools.SB_EXPOSE_TOOL       # Expose local services to the internet
kortix.AgentPressTools.SB_GIT_SYNC          # Sync files with Git repositories
kortix.AgentPressTools.SB_VISION_TOOL       # Analyze and understand images
kortix.AgentPressTools.BROWSER_TOOL         # Browse websites and interact with web pages
kortix.AgentPressTools.WEB_SEARCH_TOOL      # Search the web for information

Example:

agent = await client.Agent.create(
    name="Code Assistant",
    system_prompt="You help with coding tasks.",
    mcp_tools=[
        kortix.AgentPressTools.SB_FILES_TOOL,
        kortix.AgentPressTools.SB_SHELL_TOOL,
        kortix.AgentPressTools.SB_GIT_SYNC
    ],
    allowed_tools=["sb_files_tool", "sb_shell_tool"]
)

---

Data Models

Message

Represents a message in a thread.

Properties:

• message_id (str): Unique message identifier
• thread_id (str): Parent thread ID
• type (MessageType): Type of message (user, assistant, tool, status)
• is_llm_message (bool): Whether this is an LLM-generated message
• content (Any): Message content (varies by type)
• created_at (str): Creation timestamp
• updated_at (str): Last update timestamp
• metadata (Any): Additional metadata

Methods:

• message.is_user_message (bool): Check if user message
• message.is_assistant_message (bool): Check if assistant message
• message.get_content_as_string() (str): Get content as string

MessageType

Enum of message types:

• MessageType.USER: User message
• MessageType.ASSISTANT: Assistant message
• MessageType.TOOL: Tool result
• MessageType.STATUS: Status update
• MessageType.ASSISTANT_RESPONSE_END: End of assistant response

Role

Enum of message roles:

• Role.USER: User role
• Role.ASSISTANT: Assistant role
• Role.SYSTEM: System role

---

Utilities

print_stream()

Utility function to print agent response streams with formatting.

from kortix.utils import print_stream

stream = await run.get_stream()
await print_stream(stream)

This utility provides:

• Colored output for different event types
• Tool usage detection and display
• XML formatting for structured content
• Progress indicators

---

Type Hints

The SDK uses Union types for flexibility:

KortixTools = Union[AgentPressTools, MCPTools]

This allows passing either built-in AgentPress tools or custom MCP tools to agent creation methods.

---

Async Context Managers

For proper resource cleanup, you can use async context managers:

async with kortix.Kortix(api_key="your-key") as client:
    agent = await client.Agent.create(
        name="Test",
        system_prompt="Test agent"
    )
    # Client will be automatically closed