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 Agent configuration object
Display name for the agent
URL-friendly identifier. Must be unique per tenant.
Human-readable description of the agent’s purpose
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" , });
Initial status — always “DRAFT”
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
version = await zaby.agents.publish(agent_id) version_id = version[ "id" ]
const version = await zaby . agents . publish ( agent_id ); const version_id = version . id ;
Version identifier (used for deployment)
Deploy
Version ID from the publish step
One of “TEST” or “PRODUCTION”
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
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 CORS origins for browser-based runtime
Default TTL for generated tokens
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
apps = await zaby.external_apps.list({ "status" : "ACTIVE" })
const apps = await zaby . externalApps . list ({ status: "ACTIVE" });
app = await zaby.external_apps.get(app_id)
const app = await zaby . externalApps . get ( app_id );
await zaby.external_apps.update(app_id, { "name" : "Updated Name" })
await zaby . externalApps . update ( app_id , { name: "Updated Name" });
Enable browser-based runtime
Enable server-side runtime (required for ZabyRuntime)
Enable approval requests during runs
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”.
Single object with all parameters
Quota policy ID (create via runtimeTokenPolicies.create)
Runtime channel: "server", "web", "mobile" (default: "server")
Token lifespan in seconds (default: 600)
Maximum uses before token expires
Permission scopes for the token
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:
await zaby.runtime_tokens.record_feedback(run_id, { "rating" : 5 , "comment" : "Excellent response!" , })
await zaby . runtimeTokens . recordFeedback ( run_id , { rating: 5 , comment: "Excellent response!" , });
await zaby.agents.attach_knowledge_base(agent_id, { "knowledgeBaseId" : kb_id})
await zaby . agents . attachKnowledgeBase ( agent_id , { knowledgeBaseId: kb_id });
await zaby.agents.attach_skill(agent_id, { "skillId" : skill_id})
await zaby . agents . attachSkill ( agent_id , { skillId: skill_id });
Test & run
result = await zaby.agents.test_run(agent_id, { "input" : "Hello" })
const result = await zaby . agents . testRun ( agent_id , { input: "Hello" });
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 ;
progress = await zaby.agents.get_run_progress(run_id)
const progress = await zaby . agents . getRunProgress ( run_id );
events = await zaby.agents.list_run_events(run_id, { "limit" : 100 })
const events = await zaby . agents . listRunEvents ( run_id , { limit: 100 });
tokens = await zaby.agents.playground_runtime_tokens(agent_id)
const tokens = await zaby . agents . playgroundRuntimeTokens ( agent_id );
Approvals Approval request identifier
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 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.
