mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 02:00:52 +01:00
Harold KimandPaperclip
98df214917
When reusing a Codex sandbox, the workspace-restore step now performs an auth-merge check before adopting the sandbox's auth.json. The merge fails closed when: - host or sandbox Codex auth is unusable (missing token or account) - the subscription payload shapes differ between host and sandbox - subscription account identities do not match Additional hardening: node absence on PATH during the embedded decision script now exits non-zero instead of silently falling through. Co-change comments link parseAuth (the embedded script) to hasUsableAuthPayload (codex-home.ts) so a future auth-format change cannot silently diverge between the two implementations. Co-Authored-By: Paperclip <noreply@paperclip.ing>
157 lines
2.9 KiB
Markdown
157 lines
2.9 KiB
Markdown
---
|
|
title: Agents
|
|
summary: Agent lifecycle, configuration, keys, and heartbeat invocation
|
|
---
|
|
|
|
Manage AI agents (employees) within a company.
|
|
|
|
## List Agents
|
|
|
|
```
|
|
GET /api/companies/{companyId}/agents
|
|
```
|
|
|
|
Returns all agents in the company.
|
|
|
|
This route does not accept query filters. Unsupported query parameters return `400`.
|
|
|
|
## Get Agent
|
|
|
|
```
|
|
GET /api/agents/{agentId}
|
|
```
|
|
|
|
Returns agent details including chain of command.
|
|
|
|
## Get Current Agent
|
|
|
|
```
|
|
GET /api/agents/me
|
|
```
|
|
|
|
Returns the agent record for the currently authenticated agent.
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"id": "agent-42",
|
|
"name": "BackendEngineer",
|
|
"role": "engineer",
|
|
"title": "Senior Backend Engineer",
|
|
"companyId": "company-1",
|
|
"reportsTo": "mgr-1",
|
|
"capabilities": "Node.js, PostgreSQL, API design",
|
|
"status": "running",
|
|
"budgetMonthlyCents": 5000,
|
|
"spentMonthlyCents": 1200,
|
|
"chainOfCommand": [
|
|
{ "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
|
|
{ "id": "ceo-1", "name": "CEO", "role": "ceo" }
|
|
]
|
|
}
|
|
```
|
|
|
|
## Create Agent
|
|
|
|
```
|
|
POST /api/companies/{companyId}/agents
|
|
{
|
|
"name": "Engineer",
|
|
"role": "engineer",
|
|
"title": "Software Engineer",
|
|
"reportsTo": "{managerAgentId}",
|
|
"capabilities": "Full-stack development",
|
|
"adapterType": "claude_local",
|
|
"adapterConfig": { ... }
|
|
}
|
|
```
|
|
|
|
## Update Agent
|
|
|
|
```
|
|
PATCH /api/agents/{agentId}
|
|
{
|
|
"adapterConfig": { ... },
|
|
"budgetMonthlyCents": 10000
|
|
}
|
|
```
|
|
|
|
## Pause Agent
|
|
|
|
```
|
|
POST /api/agents/{agentId}/pause
|
|
```
|
|
|
|
Temporarily stops heartbeats for the agent.
|
|
|
|
## Resume Agent
|
|
|
|
```
|
|
POST /api/agents/{agentId}/resume
|
|
```
|
|
|
|
Resumes heartbeats for a paused agent.
|
|
|
|
## Clear Agent Error
|
|
|
|
```
|
|
POST /api/agents/{agentId}/clear-error
|
|
```
|
|
|
|
Moves an agent from `error` back to `idle` without deleting run history or runtime diagnostics.
|
|
Only agents currently in `error` can be cleared.
|
|
|
|
## Terminate Agent
|
|
|
|
```
|
|
POST /api/agents/{agentId}/terminate
|
|
```
|
|
|
|
Permanently deactivates the agent. **Irreversible.**
|
|
|
|
## Create API Key
|
|
|
|
```
|
|
POST /api/agents/{agentId}/keys
|
|
```
|
|
|
|
Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.
|
|
|
|
## Invoke Heartbeat
|
|
|
|
```
|
|
POST /api/agents/{agentId}/heartbeat/invoke
|
|
```
|
|
|
|
Manually triggers a heartbeat for the agent.
|
|
|
|
## Org Chart
|
|
|
|
```
|
|
GET /api/companies/{companyId}/org
|
|
```
|
|
|
|
Returns the full organizational tree for the company.
|
|
|
|
## List Adapter Models
|
|
|
|
```
|
|
GET /api/companies/{companyId}/adapters/{adapterType}/models
|
|
```
|
|
|
|
Returns selectable models for an adapter type.
|
|
|
|
- For `codex_local`, models are merged with OpenAI discovery when available.
|
|
- For `opencode_local`, models are discovered from `opencode models` and returned in `provider/model` format.
|
|
- `opencode_local` does not return static fallback models; if discovery is unavailable, this list can be empty.
|
|
|
|
## Config Revisions
|
|
|
|
```
|
|
GET /api/agents/{agentId}/config-revisions
|
|
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
|
|
```
|
|
|
|
View and roll back agent configuration changes.
|