agents24

Last Updated: 2026-07-16

Unified Python SDK for Agents24.

Version 0.3.0 adds trusted client-deployment administration and server-side deployment-session minting while retaining protocol contract 0.2.0.

Interrupted runs use the strict V2 resume envelope: schema_version = "agents24.hitl.resume.v2", one exact interrupt_id, one approve | reject | connect | skip action, and an optional comment. Reattach after every successful or idempotent resolution.

Endpoint methods are generated from packages/agents24-sdk-contract/agents24.sdk.json. Do not edit files under agents24/generated/ directly. For SDK maintenance, see docs/references/agents24_sdk_development_guide.md.

from agents24 import Agents24

client = Agents24(
    base_url="http://localhost:8000",
    api_key="tpk_...",
    organization_id="org-id",
)

agent = client.agent({
    "name": "Support Agent",
    "instructions": "Answer briefly.",
}).create()

client.agents.publish(agent["id"])

Client Runtime Administration

Use organization credentials only in trusted server code to manage deployment clients and mint scoped end-user sessions:

deployment = client.client_deployments.create({
    "agent_id": "agent-id",
    "agent_version_id": "version-id",
    "name": "Customer chat",
    "auth_modes": ["backend_exchange"],
    "allowed_origins": ["https://customer.example"],
})

session = client.client_sessions.create_backend_session(
    deployment["id"],
    {
        "subject": "customer-user-42",
        "browser_origin": "https://customer.example",
        "requested_capabilities": ["chat.stream", "threads.read"],
    },
)

Return only the deployment-session credentials required by the end-user client. Never expose the organization API key.

Published-Agent Runtime

Use client.embed from server code to call a published agent through the public embed runtime:

def on_event(event):
    print(event["event"])

result = client.embed.stream_agent(
    "published-agent-id",
    {
        "input": "Help me with my account.",
        "external_user_id": "customer-user-123",
    },
    on_event=on_event,
)

The namespace also includes thread detail/delete, run-context, cancel, and attachment-upload methods.

Thread history can be listed for one agent or across several agents:

threads = client.embed.list_agent_threads(
    "published-agent-id",
    external_user_id="customer-user-123",
)

sidebar_threads = client.embed.list_agent_threads_multi({
    "agent_ids": ["agent-a", "agent-b"],
    "external_user_id": "customer-user-123",
})

Async backends can use AsyncAgents24.embed.list_agent_threads_multi(agent_ids, external_user_id=...).

Artifact Authoring

Artifact code imports lightweight helpers from agents24.artifacts:

from pydantic import BaseModel, Field

from agents24.artifacts import tool


class EchoInput(BaseModel):
    text: str = Field(description="Text to echo.")


class EchoOutput(BaseModel):
    text: str


@tool(
    name="echo",
    input_schema=EchoInput,
    output_schema=EchoOutput,
)
async def echo(input, config, context):
    return {"text": input["text"]}

The agents24.artifacts module is transport-free and safe for artifact runtime code. If artifact code imports Pydantic, declare pydantic as an artifact dependency.

Self-hosted Python services can expose decorated tools through the framework-neutral server helper:

from agents24.server import create_artifact_server

server = create_artifact_server(
    exports=[echo],
    signing_secret="shared-environment-secret",
)

manifest = server.manifest()
health = server.health()
response = await server.invoke(body=request_body, headers=request_headers)

Use a built-in adapter when the SDK should create the application and mount the protocol routes:

from agents24.server_adapters import create_artifact_fastapi_app

app = create_artifact_fastapi_app(
    exports=[echo],
    signing_secret="shared-environment-secret",
)

Adapters are available for FastAPI, Starlette, Flask, Django urlpatterns, and aiohttp. Application adapters create a new app by default or mount into an existing app passed as app=. Install only the selected extra, for example agents24[fastapi]; agents24[server] installs every supported framework adapter.

For custom providers, keep using ArtifactServer directly or wrap create_artifact_asgi_app() / create_artifact_wsgi_app(). server.routes() exposes the canonical method/path list and await server.dispatch(...) provides framework-independent routing and normalized JSON responses.

Development

pnpm run generate:sdk
pnpm run check:sdk-contract
pnpm run test:agents24-python

Generated endpoint methods stay in parity with the canonical TypeScript @agents24/node package.