Metadata-Version: 2.4
Name: agents24
Version: 0.5.0
Summary: Unified Python SDK for Agents24 agent runtime and control APIs.
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: requests>=2.31.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.110; extra == "fastapi"
Requires-Dist: python-multipart>=0.0.9; extra == "fastapi"
Provides-Extra: starlette
Requires-Dist: starlette>=0.36; extra == "starlette"
Provides-Extra: flask
Requires-Dist: flask>=3.0; extra == "flask"
Requires-Dist: asgiref>=3.8; extra == "flask"
Provides-Extra: django
Requires-Dist: django>=5.0; extra == "django"
Provides-Extra: aiohttp
Requires-Dist: aiohttp>=3.9; extra == "aiohttp"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: python-multipart>=0.0.9; extra == "server"
Requires-Dist: starlette>=0.36; extra == "server"
Requires-Dist: flask>=3.0; extra == "server"
Requires-Dist: asgiref>=3.8; extra == "server"
Requires-Dist: django>=5.0; extra == "server"
Requires-Dist: aiohttp>=3.9; extra == "server"
Dynamic: license-file

# agents24

Last Updated: 2026-08-12

Unified Python SDK for Agents24.

Runtime attachment uploads return durable metadata. Use `client.agents.create_attachment_content_access(...)` or `client.embed.create_attachment_content_access(...)` to mint an authorized short-lived inline or direct-download URL.

Interrupted runs use the strict V2 resume envelope: `schema_version = "agents24.hitl.resume.v2"`, one exact `interrupt_id`, and one `approve | reject | connect | skip | respond` action. `respond` carries ordered structured answers instead of a 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`.

```python
from agents24 import Agents24

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

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:

```python
deployment = client.client_deployments.create({
    "agent_id": "agent-id",
    "resource_policy_set_id": "policy-set-id",
    "version_policy": {"mode": "latest_published"},
    "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.
Use `{"mode": "pinned", "version_id": "..."}` when a deployment must remain on one immutable Agent version.
Use `client.client_deployments.update(id, {"lifecycle_status": "inactive"})` for a reversible stop and `client.client_deployments.delete(id)` for irreversible deletion. Active deployments require a Resource Policy; removing the assignment makes them inactive. There is no `revoke()` method.

## Published-Agent Runtime

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

```python
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,
)
```

Omitting `agent_version_id` resolves the Agent's latest published version. Pass an exact
`agent_version_id` in the request only for a version-pinned server run.

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:

```python
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=...)`.

## FastAPI BFF

Install `agents24[fastapi]` when a browser application should reach one
published Agent through a customer-owned, same-origin FastAPI backend:

```python
from agents24 import AsyncAgents24
from agents24.bff.fastapi import (
    AgentBffPrincipal,
    AgentBffPrincipalResolution,
    create_agents24_bff_router,
)

client = AsyncAgents24(
    base_url="https://api.agents24.dev",
    api_key="tpk_...",
)

async def resolve_principal(request):
    user = await authenticate_application_request(request)
    return AgentBffPrincipal(subject=str(user.id), issuer="https://app.example")

app.include_router(create_agents24_bff_router(
    client=client,
    agent_id="published-agent-id",
    agent_version_id=None,
    resolve_principal=resolve_principal,
))
```

The default prefix is `/api/agents24`. The adapter derives identity on the
server, fixes Agent/version scope at construction, rejects cross-origin browser
requests, forwards idempotency and attach cursors, distinguishes stream detach
from explicit run cancellation, advertises `feedback.write`, forwards durable
response feedback through `PUT /runs/{run_id}/feedback`, and projects failures
as sanitized `agents24.failure.v1` values. Close the shared `AsyncAgents24`
client during the FastAPI application shutdown lifecycle. A resolver may
return `AgentBffPrincipalResolution` when it must add response headers. Pass
`revoke_principal=` when `/session/revoke` must also invalidate the host
application session.

The BFF requires an API key and Agent ID, not a Client Deployment. `issuer` is optional: omit it for an application-local subject, or provide a stable issuer for an authenticated customer who must receive organization-wide governance across Agents or applications.

## Customer Resource Policies

Sync and async clients expose `resource_policies` methods for list, customer assignment set/get/clear, effective projection, quota-schedule update, and explicit reset. Customer `{ issuer, subject }` identity stays in JSON request bodies. Mutation `RequestOptions` must supply an idempotency key; organization keys require `resource_policies.read` and explicit `resource_policies.write` for mutations.

## Artifact Authoring

Artifact code imports lightweight helpers from `agents24.artifacts`:

```python
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:

```python
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)
```

Signed HMAC invocation is the default. For an intentionally public endpoint, set
`auth_mode="none"` and omit `signing_secret`; the manifest advertises that mode
so Agents24 can reject mismatched connection configuration.

Every server and framework adapter also exposes
`POST /.well-known/agents24/artifact/verify`. During registration Agents24 sends
a random challenge, signed only in signed mode. Signed servers return a
domain-separated HMAC proof so the platform can verify the exact shared secret
without transmitting or returning it. Unsigned servers return the matching
challenge without a proof.

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

```python
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

```bash
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.
