@octavus/docs 4.2.0 → 5.1.0

package/content/07-workforce-agents/02-sdk.md

@@ -0,0 +1,105 @@
+---
+title: Using the SDK
+description: Drive a Workforce Agent with the @octavus/server-sdk workforce client.
+---
+
+# Using the SDK
+
+`@octavus/server-sdk` ships a `workforce` client for driving an agent with its per-agent key.
+
+## Install
+
+```bash
+npm install @octavus/server-sdk@{{VERSION:@octavus/server-sdk}}
+```
+
+## Set up the client
+
+Construct `OctavusClient` with your agent's API key:
+
+```ts
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: 'https://octavus.ai',
+  apiKey: process.env.OCTAVUS_AGENT_KEY, // oct_agt_...
+});
+```
+
+## Run a task and wait for the result
+
+`run()` is the all-in-one method: it dispatches a message, polls until the run finishes, and returns the completed thread.
+
+```ts
+const thread = await client.workforce.run(agentId, 'Summarize the latest sales report');
+
+console.log(thread.status); // 'completed' | 'failed' | 'cancelled'
+console.log(thread.messages); // the full conversation, including the agent's reply
+```
+
+The agent's latest turn is at the end of `thread.messages`.
+
+## Dispatch and poll manually
+
+For more control, dispatch and read the thread yourself:
+
+```ts
+const { threadId } = await client.workforce.dispatch(agentId, 'Research our top 3 competitors');
+
+const thread = await client.workforce.getThread(agentId, threadId);
+if (thread.status === 'completed') {
+  // ...
+}
+```
+
+`waitForCompletion()` does the polling loop for you until the thread is terminal:
+
+```ts
+const { threadId } = await client.workforce.dispatch(agentId, 'Draft the Q3 board update');
+const thread = await client.workforce.waitForCompletion(agentId, threadId);
+```
+
+## Follow up in the same thread
+
+Continue a thread with another message. It runs after the current turn finishes.
+
+```ts
+await client.workforce.followUp(agentId, threadId, 'Now turn that into a slide deck');
+const thread = await client.workforce.waitForCompletion(agentId, threadId);
+```
+
+## Options
+
+`run()` and `waitForCompletion()` accept polling options. Full runs can take several minutes, so the defaults are generous.
+
+| Option           | Type        | Default  | Description                                   |
+| ---------------- | ----------- | -------- | --------------------------------------------- |
+| `pollIntervalMs` | number      | `3000`   | Delay between status checks                   |
+| `timeoutMs`      | number      | `900000` | Max time to wait before throwing (15 minutes) |
+| `signal`         | AbortSignal | -        | Cancel the wait early                         |
+
+`dispatch()`, `followUp()`, and `run()` also accept `files` (an array of `FileReference`) to attach hosted files to the message.
+
+```ts
+const thread = await client.workforce.run(agentId, 'Review this spec', {
+  timeoutMs: 30 * 60 * 1000, // 30 minutes
+  pollIntervalMs: 5000,
+});
+```
+
+If the timeout elapses first, `waitForCompletion()` and `run()` throw. The run keeps going on the server, so you can read it later with `getThread()`.
+
+## Result shape
+
+`getThread()`, `waitForCompletion()`, and `run()` return a thread:
+
+| Field           | Type           | Description                                                                                                    |
+| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
+| `threadId`      | string         | The thread identifier                                                                                          |
+| `status`        | string         | `idle`, `queued`, `pending`, `running`, `completed`, `failed`, or `cancelled`                                  |
+| `failureReason` | string \| null | Why the run failed, when `status` is `failed`                                                                  |
+| `messages`      | UIMessage[]    | The conversation - text, tool and skill steps, and files (see [UIMessage parts](/docs/api-reference/sessions)) |
+
+Use `isTerminalThreadStatus(status)` to check whether a run has finished.
+
+The same operations are available as plain HTTP - see the [API reference](/docs/workforce-agents/api-reference).

package/content/07-workforce-agents/03-api-reference.md

@@ -0,0 +1,146 @@
+---
+title: API Reference
+description: REST endpoints for the Workforce Agents API.
+---
+
+# Workforce Agents API
+
+Drive a single agent over HTTP. Every request is authenticated with that agent's API key, sent as a bearer token:
+
+```
+Authorization: Bearer oct_agt_...
+```
+
+All endpoints are scoped to one agent through the `{agentId}` path segment - find the agent ID in the agent's page URL in the dashboard. A key only works for the agent it was created for.
+
+## Start a thread
+
+Dispatch a message to the agent. This starts a new thread and returns immediately.
+
+```
+POST /api/v1/workforce/agents/{agentId}/threads
+```
+
+### Request Body
+
+```json
+{
+  "message": "Summarize the latest sales report"
+}
+```
+
+| Field     | Type            | Required | Description                       |
+| --------- | --------------- | -------- | --------------------------------- |
+| `message` | string          | Yes      | The task or message for the agent |
+| `files`   | FileReference[] | No       | Hosted file attachments           |
+
+### Response
+
+Returns `201`.
+
+```json
+{
+  "threadId": "cm5xyz123abc456def",
+  "status": "pending"
+}
+```
+
+Poll the [Get a thread](#get-a-thread) endpoint until the status is terminal.
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads \
+  -H "Authorization: Bearer oct_agt_..." \
+  -H "Content-Type: application/json" \
+  -d '{ "message": "Summarize the latest sales report" }'
+```
+
+## Get a thread
+
+Read a thread's status and messages. Poll this until the run finishes.
+
+```
+GET /api/v1/workforce/agents/{agentId}/threads/{threadId}
+```
+
+### Response
+
+```json
+{
+  "threadId": "cm5xyz123abc456def",
+  "status": "completed",
+  "failureReason": null,
+  "messages": []
+}
+```
+
+| Field           | Type           | Description                                                                   |
+| --------------- | -------------- | ----------------------------------------------------------------------------- |
+| `threadId`      | string         | The thread identifier                                                         |
+| `status`        | string         | `idle`, `queued`, `pending`, `running`, `completed`, `failed`, or `cancelled` |
+| `failureReason` | string \| null | Why the run failed, when `status` is `failed`                                 |
+| `messages`      | UIMessage[]    | The conversation - see [UIMessage parts](/docs/api-reference/sessions)        |
+
+Keep polling while the status is `pending`, `queued`, or `running`. Stop when it is `completed`, `failed`, or `cancelled`.
+
+### Example
+
+```bash
+curl https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID \
+  -H "Authorization: Bearer oct_agt_..."
+```
+
+## Follow up in a thread
+
+Send another message into an existing thread. If the agent is still working the message runs after the current turn finishes; otherwise it starts immediately.
+
+```
+POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/messages
+```
+
+### Request Body
+
+```json
+{
+  "message": "Now turn that into a slide deck"
+}
+```
+
+| Field     | Type            | Required | Description             |
+| --------- | --------------- | -------- | ----------------------- |
+| `message` | string          | Yes      | The follow-up message   |
+| `files`   | FileReference[] | No       | Hosted file attachments |
+
+### Response
+
+Returns `202`.
+
+```json
+{
+  "threadId": "cm5xyz123abc456def",
+  "status": "running"
+}
+```
+
+Poll [Get a thread](#get-a-thread) for the new run's result.
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID/messages \
+  -H "Authorization: Bearer oct_agt_..." \
+  -H "Content-Type: application/json" \
+  -d '{ "message": "Now turn that into a slide deck" }'
+```
+
+## Errors
+
+Errors return `{ "error": string, "code": string }` with an HTTP status:
+
+| Status | Meaning                                           |
+| ------ | ------------------------------------------------- |
+| `401`  | Missing or invalid API key                        |
+| `402`  | The agent is blocked by a usage or spending limit |
+| `403`  | The key is not authorized for this agent          |
+| `404`  | The thread does not exist for this agent          |

package/content/07-workforce-agents/_meta.md

@@ -0,0 +1,4 @@
+---
+title: Workforce Agents
+description: Automate Octavus Agents over the API - dispatch a task, poll for completion, and read the result.
+---