mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-13 07:12:00 +01:00
168 lines
3.5 KiB
Markdown
168 lines
3.5 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.
|
|
|
|
## Read execution environment identity
|
|
|
|
Board users with organization access can list environments with
|
|
`GET /api/companies/{companyId}/environments` or read one with
|
|
`GET /api/environments/{environmentId}`. These routes read instance environments.
|
|
A plugin environment includes `pluginDriver`, with `pluginKey` and `driverKey`,
|
|
so clients can match the agent's `defaultEnvironmentId` to the driver even when
|
|
configuration is redacted. This field does not contain driver configuration,
|
|
environment variables, or credentials. An agent with no default inherits the
|
|
instance default.
|
|
|
|
## 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": "cto" },
|
|
{ "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.
|