# Build an agent on Sensei

Your agent can drive Sensei through the MCP server, the CLI or the API. Whichever it uses, the same rules apply. Follow each turn to its end. Answer the agent in the session when it asks. Stop when a person or the credit limit stops you.

## Pick a client

| Client | Best for | How it follows a turn | Set up |
| --- | --- | --- | --- |
| MCP server | A coding agent such as Claude Code, Codex or Cursor. | `ship` starts the work, `watch` follows the job and returns the last reply, and `submit` opens the pull request. | [Connect your coding agent](https://kosuke.ai/docs/interfaces/mcp.md) |
| CLI | Shell scripts, and agents that run commands. | `kosuke sessions jobs watch` streams the turn's events as they happen and exits when the job ends. | [Sensei CLI](https://kosuke.ai/docs/interfaces/cli.md) |
| API | Your own code, in any language. | Poll the job until it ends, then read the session's messages. Generate a client from the OpenAPI document. | [Quickstart](https://kosuke.ai/docs/api/quickstart.md) |

Every client acts as its member. The CLI and the API use an [API key](https://kosuke.ai/docs/api/authentication.md). The MCP server signs the member in through the browser, or takes an API key from a client with no browser.

## Rules your agent follows

1. Read `delivery` after every send. `job` gives a `chatJobId` to follow. `queued` means the message waits Up next behind the running turn. See [Follow a turn](https://kosuke.ai/docs/api/turns.md).
2. Follow each turn to its end. Wait until the job leaves `pending` and `running`, polling every few seconds or streaming with `kosuke sessions jobs watch`. See [Follow a turn](https://kosuke.ai/docs/api/turns.md).
3. Answer the agent's Clarifications. A job that ends `awaiting_response` holds questions in its last message, and Up next pauses. Send the answers as an ordinary message. See [Follow a turn](https://kosuke.ai/docs/api/turns.md).
4. Read the reply from the messages. The job carries its status, errors and timestamps, not the reply. The agent's words are in the session's messages. See [Follow a turn](https://kosuke.ai/docs/api/turns.md).
5. Wake the sandbox before you read files, the diff or git state. Request the session's preview, and wait while it reports `provisioning`. A paused sandbox answers the changed-file list with an empty list and the patch with 503. See [Sandboxes and previews](https://kosuke.ai/docs/api/sandboxes.md).
6. Stop on 402 `CREDIT_LIMIT_REACHED`. Retrying fails until an admin sorts out billing. The preview shows the same state as `creditLimitReached: true`. See [Responses and errors](https://kosuke.ai/docs/api/errors.md).
7. Stop on `JOB_STOPPED` or a job that ends `cancelled`. A person stopped that turn on purpose. Wait for them before you start another. See [Follow a turn](https://kosuke.ai/docs/api/turns.md).
8. Send model ids as `provider:model__effort`, such as `anthropic:opus__high`. On a send, Sensei ignores an id it cannot run and keeps the session's model, so read the session back. See [Follow a turn](https://kosuke.ai/docs/api/turns.md).
9. Send skills as messages. `/kosuke:open-pr` opens the pull request. `/kosuke:sync-branch` brings in the Target Branch, or the open pull request's base once there is one. Codex sessions take `$kosuke:open-pr` and `$kosuke:sync-branch`. See [Pull requests and sync](https://kosuke.ai/docs/endpoint-reference/pull-requests-and-sync.md).
10. Read a 404 as "not found or no access". Project routes answer 404 for both, so do not retry one. See [Responses and errors](https://kosuke.ai/docs/api/errors.md).
11. Give each agent its own API key. Revoke it when the agent retires. See [Authentication](https://kosuke.ai/docs/api/authentication.md).

## A turn from start to finish

With the MCP server, one change takes four tool calls:

1. `ship` with the project id and the prompt. It returns the session and the job.
2. `watch` with the project id, the session id and the job id. Call it again while it returns `done: false`.
3. `submit` with the project id and the session id. It sends `/kosuke:open-pr`, or `$kosuke:open-pr` on Codex, and returns the job. While a turn is running, it returns `delivery: queued` instead.
4. `watch` on that job. The pull request link is on the session once the job ends.

The same flow in curl is in [Ship a change end to end](https://kosuke.ai/docs/recipes/ship-a-change-end-to-end.md).

## Next steps

- [Follow a turn](https://kosuke.ai/docs/api/turns.md)
- [Sandboxes and previews](https://kosuke.ai/docs/api/sandboxes.md)
- [Ship a change end to end](https://kosuke.ai/docs/recipes/ship-a-change-end-to-end.md)