Skip to main content

Run your agents from code with the Workforce Agents API

Give an Octavus Agent a task from a script, backend, or CI job, wait for it to finish, and read what it did.

The Workforce Agents API lets you give one of your Octavus Agents a task without a browser: send it a message, wait for it to finish, and read what it did. It is built for automation - CI pipelines, scheduled jobs, and backend code that hands work to an agent and collects the result. Every run is a normal Thread on the agent in the dashboard, live while it runs and afterward, so you can follow it there too.

You need:

  • An agent in your organization that you have access to.
  • A verified organization. If the agent's API settings say your organization is not verified, contact support@octavus.ai.
  • A place to run server-side code or scripts. An API key is a secret and never belongs in a browser or a mobile app.

How a run works

  1. Start a thread by sending the agent a message. The API answers right away with a threadId.
  2. Poll the thread every few seconds until its status is final.
  3. Read the thread's messages to get the agent's reply and anything it produced.

An agent runs one task at a time on its computer. A thread started while the agent is busy waits in line (queued) and starts when the agent is free. Full runs often take several minutes.

StatusMeaning
pendingSent, waiting to start
queuedWaiting for the agent to finish its current run
runningThe agent is working
completedFinished (final)
failedEnded with an error; failureReason says why (final)
cancelledStopped (final)
blockedCould not run because a plan allowance or spending limit was reached; failureReason says which (final)

Keep polling while the status is pending, queued, or running. Stop at completed, failed, cancelled, or blocked.

Create an API key

Each agent has its own keys. A key drives only the agent it was created for and can never call another one.

  1. In the dashboard, open the agent and go to Settings -> API.
  2. Select Create API key and name it after the job or system that will use it.
  3. Copy the key. It starts with oct_agt_ and is shown only once.
  4. Store it where your code reads secrets: an environment variable, or your CI's secret store.

To revoke a key, delete it on the same page. Anything using it fails on its next request.

Treat the key like a password. Anyone who has it can give this agent work and read its threads. Never commit it to a repository or ship it in client-side code.

You also need the agent's ID: open the agent in the dashboard and copy the segment after /agents/ in the address bar, https://octavus.ai/agents/<agentId>/....

Run your first task

Every request goes to https://octavus.ai and carries the key as a bearer token:

text
Authorization: Bearer oct_agt_...

The examples use two environment variables, AGENT_ID and OCTAVUS_AGENT_KEY.

1. Start a thread

bash
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads" \
  -H "Authorization: Bearer $OCTAVUS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize the latest sales report" }'
json
{ "threadId": "cm5xyz123abc456def", "status": "pending" }

2. Poll until it finishes

bash
curl "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID" \
  -H "Authorization: Bearer $OCTAVUS_AGENT_KEY"

Read status from the response and repeat every few seconds until it is final.

3. Read the reply

The same response carries messages: the conversation, in order. Each message has a role (user or assistant) and a list of parts. The agent's reply is the last message with role: "assistant". Its words are in that message's text parts, and anything it produced for you (a document, a spreadsheet) is a file part with a download url. Other part types, such as tool-call, show the steps the agent took.

An abbreviated response:

json
{
  "threadId": "cm5xyz123abc456def",
  "status": "completed",
  "failureReason": null,
  "messages": [
    {
      "role": "user",
      "parts": [{ "type": "text", "text": "Summarize the latest sales report", "status": "done" }]
    },
    {
      "role": "assistant",
      "parts": [
        { "type": "tool-call", "title": "Reading the report", "status": "done" },
        { "type": "text", "text": "Q3 revenue was up 12% ...", "status": "done" },
        { "type": "file", "mediaType": "application/pdf", "filename": "summary.pdf", "url": "https://..." }
      ]
    }
  ],
  "usage": { "costUsd": 0.0421, "totalTokens": 19441 },
  "startedAt": "2026-03-04T10:12:03.418Z",
  "completedAt": "2026-03-04T10:19:47.902Z"
}

A complete example

Start a thread, wait for it, and print the reply. Python, standard library only:

python
import json
import os
import time
import urllib.request

BASE = f"https://octavus.ai/api/v1/workforce/agents/{os.environ['AGENT_ID']}"
HEADERS = {
    "Authorization": f"Bearer {os.environ['OCTAVUS_AGENT_KEY']}",
    "Content-Type": "application/json",
}
FINAL = {"completed", "failed", "cancelled", "blocked"}


def call(method, path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    request = urllib.request.Request(BASE + path, data=data, method=method, headers=HEADERS)
    with urllib.request.urlopen(request) as response:
        return json.load(response)


thread = call("POST", "/threads", {"message": "Summarize the latest sales report"})
while thread["status"] not in FINAL:
    time.sleep(5)
    thread = call("GET", f"/threads/{thread['threadId']}")

if thread["status"] != "completed":
    raise SystemExit(f"{thread['status']}: {thread['failureReason']}")

reply = [m for m in thread["messages"] if m["role"] == "assistant"][-1]
print("".join(part["text"] for part in reply["parts"] if part["type"] == "text"))

Continue the conversation

Send another message into the same thread to build on what the agent did. If the agent is still working, the message runs after the current turn finishes; otherwise it starts right away.

bash
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID/messages" \
  -H "Authorization: Bearer $OCTAVUS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Now turn that into a slide deck" }'

The response is 202 with the thread's current status. Poll the thread as before for the new result; completedAt is cleared while the new turn runs and set again when it finishes.

Stop a run

Cancel a run that has taken too long or is no longer needed. This is the Stop button of the dashboard: the agent is told to stop, and the run stops billing.

bash
curl -X POST "https://octavus.ai/api/v1/workforce/agents/$AGENT_ID/threads/$THREAD_ID/cancel" \
  -H "Authorization: Bearer $OCTAVUS_AGENT_KEY"

The thread reads cancelled. Cancelling a thread that has already finished changes nothing.

Send files with a task

A task can carry files: a spec to review, a spreadsheet to clean up. Host them first with the files endpoint, upload the bytes to the URL it returns, then attach the reference to your message. You can also attach a file by an https: URL you host yourself. The steps are in Attaching files.

Good practices

  • Retry safely. Send an Idempotency-Key header with a value unique to the task, such as a job ID. If the response is lost and you send the same request again, you get the thread the first request created instead of a second run.
  • Do not pile up work. To run only when the agent is free, send "ifIdle": true; a busy agent answers 409 AGENT_BUSY and nothing is created. To look before you send, read the agent with GET /api/v1/workforce/agents/$AGENT_ID: its status is idle, busy, or unavailable.
  • Poll gently. Every 3 to 5 seconds is plenty; runs take minutes, not milliseconds. Set your own time budget and cancel the run when it is exceeded.
  • Check the work before retrying. On a failed thread, read failureType: only computer_unreachable guarantees the agent did nothing. For anything else, look at messages before repeating a task with side effects, such as sending an email.
  • Keep the request ID. Every response carries a Request-Id header, and every error body a requestId. Quote it when you contact support@octavus.ai.

Verify

Open the agent in the dashboard. The thread you started is in its Threads, with your message, the agent's work, and the reply you read from the API.

Troubleshooting

What you seeWhat it means
401The key is missing, malformed, or was deleted. Send it as Authorization: Bearer oct_agt_....
403 FORBIDDENThe key belongs to a different agent than the one in the URL.
403 ORG_BLOCKEDYour organization is suspended, pending verification, or archived; the message says which.
404The thread does not exist for this agent, or the agent ID is wrong.
409 AGENT_PAUSEDAn owner paused the agent. Resume it in the dashboard.
Status blockedA plan allowance or spending limit was reached; failureReason says which. Upgrade or raise the limit, then send a new message to the same thread.
Agent unavailablepaused: resume the agent. computer_down: its computer cannot be reached; check it in the dashboard. cli_only: the agent is set to run from the Agent CLI on a machine you control, so it takes work only from there.
Cannot create a keyYour organization is not verified yet. Contact support@octavus.ai.