Kodeus SDK

Create, publish and invoke AI agents from Python. The SDK provides typed agent specifications, asynchronous execution clients, event streaming, webhook verification and a command-line authoring interface.

This version is a development preview. Use it with a compatible Kodeus environment and pin the version in your application's dependency file.

Install

Requires Python 3.10 or later:

python -m pip install "kodeus==0.3.0rc1"

Submit a task

Your organization administrator supplies the API base URL, organization ID, service-account credential and installed agent ID. The application API base URL must end in /sdk. The SDK does not choose a production or test environment for you.

import asyncio
import os
from uuid import uuid4

from kodeus.client import AsyncKodeus


async def main():
    async with AsyncKodeus(
        base_url=os.environ["KODEUS_BASE_URL"],
        org_id=os.environ["KODEUS_ORG_ID"],
        api_key=os.environ["KODEUS_API_KEY"],
    ) as client:
        agent = client.agents.get(os.environ["KODEUS_AGENT_ID"])
        run = await agent.submit(
            input={"message": "Summarize the available support options."},
            idempotency_key=str(uuid4()),
        )
        print("Run:", run.id)
        print("Session:", run.snapshot.session_id)


asyncio.run(main())

Use the input shape required by your agent. Submission returns after durable acceptance; the agent may still be running. In an application, save the command UUID and input before submitting, reuse them when retrying that command, and persist the returned run/session identifiers. Configure credentials through your environment or secret manager, never in source code.

CLI and optional integrations

kodeus --help
kodeus validate --help

Hosted agent creation and invocation do not require a local execution engine, database or message broker. The optional introspect extra enables inspection of local stdio MCP servers:

python -m pip install "kodeus[introspect]==0.3.0rc1"

Local execution, schema provisioning and some administration commands require a separately authorized Kodeus Runtime distribution. Obtain its installation instructions from your Kodeus administrator; the public SDK does not download that private package. The SDK retains the supported BYO database adapter for existing single-customer installations. Shared hosted environments use the authenticated API.

Legacy CLI authoring uses KODEUS_CLOUD_URL, and its OAuth broker uses KODEUS_AI_API_URL. Set those explicitly for the environment supplied by your administrator; they are distinct from the application client's API base URL.

License

The SDK is licensed under Apache-2.0. The separately distributed runtime and hosted services are not included in this package. Learn more at kodeus.ai.