Sokko Docs
Platform API

Agents

Create an agent in a workspace, wait until it is ready, then change, suspend, redeploy or delete it.

An agent is an always-on program in one workspace. It has a name, instructions, a model, and optionally skills, MCP servers, connected apps and the workspace's shared memory. Your product talks to it through conversations.

All paths below are relative to https://sokko.ai/api/v1.

The agent object

{
  "id": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "externalId": "order-desk",
  "name": "Order desk",
  "status": "ready",
  "modelId": "anthropic/claude-sonnet-4.6",
  "audience": "end_users",
  "replyFormat": "plain",
  "brandName": "Acme",
  "memory": true,
  "skills": ["returns-policy"],
  "mcpServers": ["orders"],
  "integrations": [],
  "recipe": null,
  "lastError": null,
  "createdAt": "2026-11-20T09:16:30.204Z",
  "updatedAt": "2026-11-20T09:17:41.877Z"
}
FieldMeaning
idThe id you use in every path of this agent.
externalIdYour own id for the agent, or null.
statusSee Statuses.
errorOnly while status is failed: { "code", "message" }.
lastErrorThe last failure of the agent's setup or upgrade: { "code", "message", "at" }, with at the time it happened. null when there is none.
modelIdThe model the agent runs on.
audienceend_users or operator. See Audience.
replyFormatplain or markdown. See Reply format.
brandNameThe brand name the agent says it is the agent of, or null. See Brand name.
memorytrue when the agent reads and writes the workspace's shared memory.
skillsNames of the workspace skills the agent has, sorted.
mcpServersNames of the workspace MCP servers the agent has, sorted.
integrationsThe apps the agent's recipe names, each as { "app", "required", "status" } with the status not_connected, pending or connected. Empty for an agent with no recipe. For every connection of the agent, read its integrations.
recipenull for an agent you created with explicit fields. For a recipe agent: { id, version, latestVersion, behind }.

The object never carries the instructions. Keep your own copy.

Create an agent

POST /workspaces/{workspaceId}/agents

This page describes the explicit form: you send every field yourself. To create an agent from a recipe, see Recipes.

FieldTypeRules
namestringRequired. One line, 2 to 60 characters. A display name.
instructionsstringRequired. 1 to 6,000 characters. Who the agent is and what it does.
modelIdstringOptional. 1 to 200 characters. Without it the agent runs on the platform's default model.
skillsstring[]Optional. Up to 50 names of skills that are active in this workspace.
mcpServersstring[]Optional. Up to 50 names of MCP servers of this workspace.
memorybooleanOptional, default false. Needs a workspace with memory.
audiencestringOptional, default end_users. end_users or operator.
replyFormatstringOptional, default plain. plain or markdown.
externalIdstringOptional. 1 to 200 characters. Your own id, unique among the live agents of the workspace.
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "order-desk",
    "name": "Order desk",
    "instructions": "You answer customers of Bakkerij Janssens. Opening hours: Tuesday to Sunday, 7:00 to 18:00. Orders for the next day close at 16:00.",
    "modelId": "anthropic/claude-sonnet-4.6",
    "skills": ["returns-policy"],
    "mcpServers": ["orders"],
    "memory": true,
    "audience": "end_users",
    "replyFormat": "plain"
  }'

The answer is the agent object with "status": "provisioning", and 201.

  • With an externalId, the same request again answers 200 with the agent that exists. The same externalId with any other field value answers 409 external_id_conflict. The externalId of a deleted agent is free again.
  • Without an externalId, every call creates a new agent.
  • The workspace needs credits before its first agent. See Credits.
  • instructions holds at most 6,000 characters. A text of exactly 6,000 is accepted, and a longer one is refused, never cut.
  • An agent created from a recipe has its own replay rule for recipeVersion: a replay must name the version the agent was created with, or leave the field out.
  • A modelId has the form maker/model. The Sokko team gives you the ids your account can use.
  • A model call is paid from the workspace's AI credits. The API has no way to give an agent a model key of your customer.
  • With "memory": true the agent uses the one memory of its workspace, for either audience. Read who shares a memory first.
  • The MCP servers of an end_users agent must fit the rules of its audience.
  • When your account has a brand name, the agent says that it is the agent of that brand. See Brand name.

Errors

StatusCodeWhen
400invalid_requestA field breaks a rule, or mcpServers names a server the workspace does not have.
402billing_inactiveYour subscription is not active, or a payment is past due.
402credits_exhaustedThe workspace has no credits. Move credits to it, then create the agent.
402memory_not_enabledYou sent memory: true and the workspace has no memory.
402plan_limitYour agent pool is full, or the workspace holds its maximum of agents.
403end_users_disabledAgents for end users are not enabled yet. Send audience: "operator".
409external_id_conflictThe externalId exists in the workspace with other fields.
409skill_not_activeA skill is unknown, still pending, failed or disabled. The message names it.
409mcp_server_not_allowed_for_end_usersmcpServers names a server that an end_users agent cannot use. See Audience.
409conflictThe agent was deleted while it was created, or the create must be sent again.

A replay of an externalId answers the agent that exists, whatever the state of your subscription is.

Statuses

StatusMeaning
preparingThe agent is reserved and its parts are being prepared. It does not run yet.
provisioningThe agent is starting.
readyThe agent runs and takes messages.
upgradingThe agent moves to a newer version of its recipe. See While an agent is upgraded.
failedThe agent could not start, or its setup did not finish. error says why.
suspendedThe agent is stopped, or is stopping. Its files and configuration are kept.
deletingThe agent is being removed.

A failed agent carries an error:

{
  "status": "failed",
  "error": {
    "code": "start_failed",
    "message": "The agent could not start. Redeploy it, or change its configuration."
  }
}

start_failed means the agent was created and did not come up: send the redeploy action, or change its model, skills or MCP servers. Every other code is a setup that did not finish (see the codes of a recipe setup): delete the agent and create it again.

lastError keeps the code and the message of the last setup or upgrade that failed, with its time. It is the place to read why an upgrade did not finish: that agent runs on, on its old version, and its status is not failed.

While an agent is upgraded

While the status is upgrading, the agent is changed step by step. These calls answer 409 agent_busy until the upgrade ends: an update, an instruction change, an action, a schedule create or delete, and a second upgrade. A delete still works, and so does every read.

Wait for ready

A new agent usually takes about a minute to start. Two ways to know when it is ready:

  • Webhook. Subscribe to agent.ready and agent.failed. See Webhooks.
  • Poll. Read the agent every few seconds until status is ready or failed.
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"

Conversations, schedules and instruction changes need a ready agent. Before that they answer 409 agent_not_ready.

List and read agents

GET /workspaces/{workspaceId}/agents
GET /workspaces/{workspaceId}/agents/{agentId}

The list comes newest first and takes limit and cursor.

curl "https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents?limit=50" \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "data": [
    {
      "id": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
      "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
      "externalId": "order-desk",
      "name": "Order desk",
      "status": "ready",
      "modelId": "anthropic/claude-sonnet-4.6",
      "audience": "end_users",
      "replyFormat": "plain",
      "brandName": "Acme",
      "memory": true,
      "skills": ["returns-policy"],
      "mcpServers": ["orders"],
      "integrations": [],
      "recipe": null,
      "lastError": null,
      "createdAt": "2026-11-20T09:16:30.204Z",
      "updatedAt": "2026-11-20T09:17:41.877Z"
    }
  ],
  "nextCursor": null
}

Only agents created through the Platform API exist here. Errors: 400 invalid_request (a bad limit or cursor), 404 not_found.

Update an agent

PATCH /workspaces/{workspaceId}/agents/{agentId}

Send at least one of name, modelId, skills, mcpServers, memory, with the rules of the create. skills and mcpServers replace the agent's list: send every name the agent keeps, or [] to remove them all.

curl -X PATCH https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "modelId": "openai/gpt-5.4", "skills": ["returns-policy", "allergens"] }'

The answer is the agent object.

  • The agent must be ready, failed or suspended. In any other status the call answers 409 agent_busy.
  • A value equal to the current one changes nothing.
  • The fields are written one after the other, not as one change. If the call answers an error after it started to write, a part of it can be applied: read the agent, then send the rest again.
  • A new model, skill list, MCP server list or memory setting can make the agent start again with the new configuration. Read the agent after the call, and wait for ready before the next message.
  • audience, replyFormat and externalId cannot be changed. Create a new agent for another audience or reply format.
StatusCodeWhen
400invalid_requestNo field, a bad value, or an MCP server the workspace lacks.
402memory_not_enabledYou sent memory: true and the workspace has no memory.
404not_foundNo such agent in this workspace.
409agent_busyThe agent is not ready, failed or suspended, or it is being upgraded.
409skill_not_activeA skill you add is not active in the workspace.
409mcp_server_not_allowed_for_end_usersAn MCP server you add cannot be used by an end_users agent. See Audience.

Replace the instructions

PUT /workspaces/{workspaceId}/agents/{agentId}/instructions
curl -X PUT https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/instructions \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "You answer customers of Bakkerij Janssens. Opening hours: Monday to Sunday, 7:00 to 18:00." }'

The answer is the agent object. The new text replaces the old one as a whole, and the agent does not restart. The text holds at most 6,000 characters, and exactly 6,000 is accepted.

When the agent has a brand name, one line that says whose agent it is goes before your text. That line does not count in the 6,000 characters.

The instructions are written to the running agent, so the agent must be ready.

StatusCodeWhen
400invalid_requestThe text is empty, too long, or the agent refused it.
404not_foundNo such agent in this workspace.
409agent_not_readyThe agent is not ready.
409agent_busyThe agent is being upgraded.
409conflictThe agent changed its own instructions at the same moment. Send it again.
503unavailableThe agent could not be reached. Try again later.

Suspend, resume, redeploy

POST /workspaces/{workspaceId}/agents/{agentId}/actions
actionWhat it does
suspendStops the agent. Its files and configuration are kept. It takes no messages.
resumeStarts a suspended agent again.
redeployStarts the agent again with its current configuration. Use it for a failed agent.

A redeploy also gives the agent the brand name that your account has at that moment.

curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT/actions \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "suspend" }'

The answer is the agent object with its new status.

  • suspend on a suspended agent and resume on an agent that is not suspended change nothing and answer the agent as it is. You can send an action again safely.
  • A suspended agent still counts in your agent pool.
  • resume and redeploy start an agent, so they need an active subscription with no payment past due. suspend always works.
StatusCodeWhen
400invalid_requestaction is not one of the three.
402billing_inactiveresume or redeploy while your subscription is not active or a payment is past due.
404not_foundNo such agent in this workspace.
409agent_busyThe agent is still being set up, is being upgraded, or is being deleted.

Delete an agent

DELETE /workspaces/{workspaceId}/agents/{agentId}
curl -X DELETE https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"

The answer is 204 with no body. From that moment the agent answers 404 and its externalId is free. The agent's own files and its app connections are removed. The workspace's skills, MCP servers and shared memory stay, also the ones a recipe added for this agent.

A delete works in every status. For an agent that is still preparing, it cancels the setup. For an agent that is upgrading, it ends the upgrade.

The conversations of a deleted agent can no longer be read through the API, but their stored records are not erased by this call. To erase them, delete the end user's data or the workspace. See Data and privacy.

Errors: 404 not_found.

Audience

audience says who talks to the agent, and how far those people are trusted. Set it at creation. It cannot be changed later.

ValueWho talks to the agent
operatorThe people of one customer of yours, who work with their own agent and are trusted with it.
end_usersMany outside people, who must not change how the agent is set up.

Two examples:

  • operator. You provide an agent to an accounting firm. The accountants of that firm talk to it in your product. They are the firm's own staff, so they may ask the agent to use its tools, to connect an app, or to change its setup.
  • end_users. One of your customers puts a support chat on its public website. Anyone on the internet can write to that agent, and each of them can try to steer it. The agent must answer them, and nothing more.

An end_users agent runs with two more rules:

  • A tool guard. It cannot change its own configuration or fetch credentials from a conversation. The tools that add an MCP server, connect an app, publish a skill, read or write stored files, or hand out an access token are refused. The agent is told that the business that operates it configures it. You connect its apps from your own product. See Integrations.
  • MCP server tokens stay off the agent's machine. A server with a bearer or header token is reached through the platform, which adds the token to each request on the way out. The token is not on the agent's machine, so a prompt cannot make the agent reveal it. A server that cannot be reached that way is refused for this agent with 409 mcp_server_not_allowed_for_end_users, at the create and at an update: today that is a token server on an http URL, so use https. A server with no authentication is reached directly.

An operator agent has neither rule: its people are trusted with its tools. It can offer a link to connect an app in a conversation. That link and its label name Sokko as the provider.

Both audiences can use the workspace's memory. One workspace has one memory, shared by all its agents and by everyone who talks to them. So create one workspace per customer, and do not put unrelated people behind one workspace's agent if they must not see each other's information.

end_users is the default, and it is not open yet. Until the Sokko team enables it, a create without "audience": "operator" answers 403 end_users_disabled. The same holds for a recipe whose audience is end_users.

Brand name

When your account has a brand name, every agent you create is told that it is the agent of your brand, and to say so when someone asks who it is. An agent named Ada of the brand Acme answers that it is Ada, the agent of Acme. GET /account shows the name as brand.name. The Sokko team sets it for you.

  • The agent object shows the name the agent uses as brandName. It is null for an account with no brand name, and while the agent is preparing.
  • At most 60 characters of the name are used, on one line.
  • The agent is not told to hide that Sokko is the provider behind it. Only the identity is yours.
  • A new brand name of your account does not reach your agents at once. Each agent gets it at its next redeploy action or at its next recipe upgrade. No call changes all agents together. Read brandName to see what an agent uses.
  • The line that names the brand inside the agent's instructions is written with the instructions. After a new brand name, set the instructions again once the agent has it.

Reply format

replyFormat tells the agent what your product renders:

  • plain: the agent answers in plain text, with no Markdown.
  • markdown: the agent formats its answers in Markdown. Render it in your product.

It is set at creation and applies to every conversation of the agent.

On this page