Skip to main content

​
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us