Agents & Provisioning

Switch between Python and TypeScript code examples using the language tabs.

The AgentsClient manages the full agent lifecycle. Access it via zaby.agents.

Create an agent

body

dict

required

Agent configuration object

body.name

string

required

Display name for the agent

body.slug

string

required

URL-friendly identifier. Must be unique per tenant.

body.description

string

Human-readable description of the agent’s purpose

Python
TypeScript

agent = await zaby.agents.create({
    "name": "Customer Support Agent",
    "slug": "support-agent",
    "description": "Handles customer inquiries",
})

const agent = await zaby.agents.create({
  name: "Customer Support Agent",
  slug: "support-agent",
  description: "Handles customer inquiries",
});

string

Unique agent identifier

status

string

Initial status — always “DRAFT”

name

string

Display name

slug

string

URL identifier

createdAt

string

ISO-8601 creation timestamp

{
  "id": "a1b2c3d4-...",
  "name": "Customer Support Agent",
  "slug": "support-agent",
  "status": "DRAFT",
  "createdAt": "2026-06-24T12:00:00Z"
}

Getting Started

Create, publish, and deploy your first agent in 5 minutes.

Runtime Client

Start runs and stream agent responses.

Manage agents

The current SDK does not include dedicated get, list, update, or delete methods on AgentsClient. These can be performed via direct API calls using the provisioning endpoints:

List: GET /api/v1/provisioning/agentic-os/agents (cursor-based pagination)
Get: GET /api/v1/provisioning/agentic-os/agents/{agentId}
Update: PATCH /api/v1/provisioning/agentic-os/agents/{agentId}
Delete: DELETE /api/v1/provisioning/agentic-os/agents/{agentId}

Publish and deploy

Agents start in DRAFT status. Publishing creates a version snapshot; deploying makes it live.

Publish

Python
TypeScript

version = await zaby.agents.publish(agent_id)
version_id = version["id"]

const version = await zaby.agents.publish(agent_id);
const version_id = version.id;

string

Version identifier (used for deployment)

Deploy

agent_version_id

string

required

Version ID from the publish step

environment

string

required

One of “TEST” or “PRODUCTION”

Python
TypeScript

deployment = await zaby.deployments.create(agent_id, {
    "agentVersionId": version_id,
    "environment": "TEST",
})
deployment_id = deployment["id"]

const deployment = await zaby.deployments.create(agent_id, {
  agentVersionId: version_id,
  environment: "TEST",
});
const deployment_id = deployment.id;

The deployment returns immediately with status PENDING. Cloudflare provisioning runs in the background. The deployment transitions to ACTIVE after roughly 12 minutes. Calling getProvisioning() before the deployment is ACTIVE returns 404.

Get provisioning details

Python
TypeScript

provisioning = await zaby.deployments.get_provisioning(deployment_id)

const provisioning = await zaby.deployments.getProvisioning(deployment_id);

External apps

External apps represent your application that embeds Zaby agents. They bridge deployments to runtime tokens.

Create

name

string

required

Display name

slug

string

required

Unique identifier

allowedOrigins

string[]

CORS origins for browser-based runtime

tokenTtlSeconds

number

Default TTL for generated tokens

Python
TypeScript

app = await zaby.external_apps.create({
    "name": "My Web App",
    "slug": "my-web-app",
    "allowedOrigins": ["https://app.example.com"],
    "tokenTtlSeconds": 600,
})

const app = await zaby.externalApps.create({
  name: "My Web App",
  slug: "my-web-app",
  allowedOrigins: ["https://app.example.com"],
  tokenTtlSeconds: 600,
});

Manage

List apps

Python
TypeScript

apps = await zaby.external_apps.list({"status": "ACTIVE"})

const apps = await zaby.externalApps.list({ status: "ACTIVE" });

Get app

Python
TypeScript

app = await zaby.external_apps.get(app_id)

const app = await zaby.externalApps.get(app_id);

Update app

Python
TypeScript

await zaby.external_apps.update(app_id, {"name": "Updated Name"})

await zaby.externalApps.update(app_id, { name: "Updated Name" });

Bind deployment

deploymentId

string

required

Deployment to bind

allowBrowserRuntime

boolean

Enable browser-based runtime

allowServerRuntime

boolean

Enable server-side runtime (required for ZabyRuntime)

allowApprovals

boolean

Enable approval requests during runs

Python
TypeScript

await zaby.external_apps.bind_deployment(app_id, {
    "deploymentId": deployment_id,
    "allowServerRuntime": True,
})

await zaby.externalApps.bindDeployment(app_id, {
  deploymentId: deployment_id,
  allowServerRuntime: true,
});

Runtime tokens

Create disposable JWT tokens for the ZabyRuntime client.

A quota policy must be created first and its ID passed as quotaPolicyId. Without it, the server returns a 500 error: “Cloudflare runtime sync snapshot is missing quotaPolicyId”.

input

dict

required

Single object with all parameters

input.externalAppId

string

required

External app ID

input.deploymentId

string

required

Deployment ID

input.quotaPolicyId

string

required

Quota policy ID (create via runtimeTokenPolicies.create)

input.externalUserId

string

required

End-user identifier

input.externalSessionId

string

Session identifier

input.channel

string

Runtime channel: "server", "web", "mobile" (default: "server")

input.ttlSeconds

number

Token lifespan in seconds (default: 600)

input.maxUses

number

Maximum uses before token expires

input.scopes

string[]

Permission scopes for the token

Python
TypeScript

token = await zaby.runtime_tokens.create({
    "externalAppId": app_id,
    "deploymentId": deployment_id,
    "quotaPolicyId": policy_id,
    "externalUserId": "user-123",
    "externalSessionId": "session-456",
    "channel": "server",
    "ttlSeconds": 600,
    "maxUses": 20,
})
runtime_token = token["token"]

const token = await zaby.runtimeTokens.create({
  externalAppId: app_id,
  deploymentId: deployment_id,
  quotaPolicyId: policy_id,
  externalUserId: "user-123",
  externalSessionId: "session-456",
  channel: "server",
  ttlSeconds: 600,
  maxUses: 20,
});
const runtime_token = token.token;

Record feedback

Record runtime feedback using the runtime token context:

run_id

string

required

Run identifier

Python
TypeScript

await zaby.runtime_tokens.record_feedback(run_id, {
    "rating": 5,
    "comment": "Excellent response!",
})

await zaby.runtimeTokens.recordFeedback(run_id, {
  rating: 5,
  comment: "Excellent response!",
});

Rotate tokens

Rotate the current runtime token, issuing a new one with the same claims:

Python
TypeScript

rotated = await zaby.runtime_tokens.rotate({
    "reason": "Scheduled rotation",
})
new_token = rotated["token"]

const rotated = await zaby.runtimeTokens.rotate({
  reason: "Scheduled rotation",
});
const new_token = rotated.token;

Rotate by unique ID

Rotate a specific runtime token using its uniqueIdHash and externalAppId:

Python
TypeScript

rotated = await zaby.runtime_tokens.rotate_by_unique_id({
    "externalAppId": app_id,
    "uniqueIdHash": "abc123...",
    "reason": "Compromised token",
})

const rotated = await zaby.runtimeTokens.rotateByUniqueId({
  externalAppId: app_id,
  uniqueIdHash: "abc123...",
  reason: "Compromised token",
});

Revoke token family

Revoke an entire token family by family ID, invalidating all tokens within it:

Python
TypeScript

await zaby.runtime_tokens.revoke_family(family_id, {
    "reason": "Policy update",
})

await zaby.runtimeTokens.revokeFamily(family_id, {
  reason: "Policy update",
});

Attach tools & knowledge

Attach MCP tool

Python
TypeScript

await zaby.agents.attach_mcp_tool(agent_id, {"toolId": installation_id})

await zaby.agents.attachMcpTool(agent_id, { toolId: installation_id });

Attach knowledge base

Python
TypeScript

await zaby.agents.attach_knowledge_base(agent_id, {"knowledgeBaseId": kb_id})

await zaby.agents.attachKnowledgeBase(agent_id, { knowledgeBaseId: kb_id });

Attach skill

Python
TypeScript

await zaby.agents.attach_skill(agent_id, {"skillId": skill_id})

await zaby.agents.attachSkill(agent_id, { skillId: skill_id });

Test & run

Test run (dry-run)

Python
TypeScript

result = await zaby.agents.test_run(agent_id, {"input": "Hello"})

const result = await zaby.agents.testRun(agent_id, { input: "Hello" });

Production run

Python
TypeScript

run = await zaby.agents.start_run(agent_id, {"input": "Hello"})
run_id = run["runId"]

const run = await zaby.agents.startRun(agent_id, { input: "Hello" });
const run_id = run.runId;

Run progress

Python
TypeScript

progress = await zaby.agents.get_run_progress(run_id)

const progress = await zaby.agents.getRunProgress(run_id);

Run events

Python
TypeScript

events = await zaby.agents.list_run_events(run_id, {"limit": 100})

const events = await zaby.agents.listRunEvents(run_id, { limit: 100 });

Playground tokens

Python
TypeScript

tokens = await zaby.agents.playground_runtime_tokens(agent_id)

const tokens = await zaby.agents.playgroundRuntimeTokens(agent_id);

Approvals

run_id

string

required

Run identifier

approval_id

string

required

Approval request identifier

Python
TypeScript

approvals = await zaby.approvals.list()
await zaby.approvals.approve(run_id, approval_id)
await zaby.approvals.reject(run_id, approval_id)

const approvals = await zaby.approvals.list();
await zaby.approvals.approve(run_id, approval_id);
await zaby.approvals.reject(run_id, approval_id);

Usage analytics

Python
TypeScript

usage = await zaby.usage.get_agent_usage({
    "agentId": agent_id,
    "from": "2026-01-01",
    "to": "2026-06-01",
})

const usage = await zaby.usage.getAgentUsage({
  agentId: agent_id,
  from: "2026-01-01",
  to: "2026-06-01",
});

MCP Client

Manage MCP servers, tools, and installations.

Knowledge Bases

Create and manage knowledge bases with documents.

Memory Client

Store and retrieve agent memory items.

Intelligence Client

Signals, rollups, and improvement tracking.

Getting Started

Clients

Guides

Agents & Provisioning

Agents & Provisioning

Create an agent

Getting Started

Runtime Client

Manage agents

Publish and deploy

External apps

Create

Manage

Runtime tokens

Record feedback

Rotate tokens

Rotate by unique ID

Revoke token family

Attach tools & knowledge

Test & run

Approvals

Usage analytics

MCP Client

Knowledge Bases

Memory Client

Intelligence Client

​Agents & Provisioning

​Create an agent

Getting Started

Runtime Client

​Manage agents

​Publish and deploy

​External apps

​Create

​Manage

​Runtime tokens

​Record feedback

​Rotate tokens

​Rotate by unique ID

​Revoke token family

​Attach tools & knowledge

​Test & run

​Approvals

​Usage analytics

MCP Client

Knowledge Bases

Memory Client

Intelligence Client

Agents & Provisioning

Create an agent

Manage agents

Publish and deploy

External apps

Create

Manage

Runtime tokens

Record feedback

Rotate tokens

Rotate by unique ID

Revoke token family

Attach tools & knowledge

Test & run

Approvals

Usage analytics