From 6e4fd078d9dd0ab73acf404f739f4dd1e923fd8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Thu, 16 Apr 2026 23:34:20 -0400 Subject: [PATCH] refactor(prompt-builder): extract API docs into markdown sections - Split 366-line api-section.ts into 11 category markdown files under src/main/prompt-builder/api-docs/ (header, agent-control, tasks, goals-projects, approvals, messages, files, knowledge, meetings, agents, sprints) - api-section.ts reduced to ~45 lines: imports each section via ?raw, substitutes {{apiUrl}}/{{companyId}}/{{agentId}}/{{runId}}/{{connectorIds}}, joins sections and appends social media addendum - Every endpoint signature, body schema, and curl example preserved verbatim so LLM instruction surface is unchanged --- .../prompt-builder/api-docs/agent-control.md | 10 + src/main/prompt-builder/api-docs/agents.md | 37 ++ src/main/prompt-builder/api-docs/approvals.md | 28 ++ src/main/prompt-builder/api-docs/files.md | 54 +++ .../prompt-builder/api-docs/goals-projects.md | 21 + src/main/prompt-builder/api-docs/header.md | 53 +++ src/main/prompt-builder/api-docs/knowledge.md | 13 + src/main/prompt-builder/api-docs/meetings.md | 19 + src/main/prompt-builder/api-docs/messages.md | 32 ++ src/main/prompt-builder/api-docs/sprints.md | 14 + src/main/prompt-builder/api-docs/tasks.md | 69 +++ src/main/prompt-builder/api-section.ts | 400 ++---------------- 12 files changed, 389 insertions(+), 361 deletions(-) create mode 100644 src/main/prompt-builder/api-docs/agent-control.md create mode 100644 src/main/prompt-builder/api-docs/agents.md create mode 100644 src/main/prompt-builder/api-docs/approvals.md create mode 100644 src/main/prompt-builder/api-docs/files.md create mode 100644 src/main/prompt-builder/api-docs/goals-projects.md create mode 100644 src/main/prompt-builder/api-docs/header.md create mode 100644 src/main/prompt-builder/api-docs/knowledge.md create mode 100644 src/main/prompt-builder/api-docs/meetings.md create mode 100644 src/main/prompt-builder/api-docs/messages.md create mode 100644 src/main/prompt-builder/api-docs/sprints.md create mode 100644 src/main/prompt-builder/api-docs/tasks.md diff --git a/src/main/prompt-builder/api-docs/agent-control.md b/src/main/prompt-builder/api-docs/agent-control.md new file mode 100644 index 00000000..0048d0e2 --- /dev/null +++ b/src/main/prompt-builder/api-docs/agent-control.md @@ -0,0 +1,10 @@ +### Get Your Identity +GET /api/agents/me +Returns your agent record with chain of command, budget info, department, and status. +Call this first to confirm your identity and understand your position. + +### Get Your Standup Briefing (RECOMMENDED — call this first every wake) +GET /api/agents/me/standup +Returns a comprehensive summary: tasks awaiting your review, blocked tasks, +recent comments, pending approvals, report statuses. Use this to prioritize your work. +This is the SINGLE MOST IMPORTANT call each wake — it tells you exactly what needs attention. diff --git a/src/main/prompt-builder/api-docs/agents.md b/src/main/prompt-builder/api-docs/agents.md new file mode 100644 index 00000000..143ece8b --- /dev/null +++ b/src/main/prompt-builder/api-docs/agents.md @@ -0,0 +1,37 @@ +### Propose a Hire +POST /api/companies/{{companyId}}/agents +Body: { + "name": "New hire display name (must not repeat role/title)", + "role": "role_title", + "title": "Descriptive title", + "department": "engineering|product|marketing|sales|hr|finance|legal|operations|customer_support|research|design|executive", + "reportsTo": "{managerAgentId — who this person reports to}", + "connectorId": "{{connectorIds}}", + "workspaceId": "{optionalWorkspaceId}", + "model": "model-identifier", + "capabilities": "Detailed description of what this hire should own and be able to do", + "budgetMonthlyUsd": 250 +} +This creates the agent in pending_approval state. The Board (human operator) must approve. +After approval, the agent becomes active and can be assigned work. + +### Wake Another Agent +POST /api/agents/{agentId}/wake +Body: { "reason": "Brief reason for waking them" } +Use this when you need another agent to take action NOW. This triggers their next heartbeat. + +### List All Agents +GET /api/companies/{{companyId}}/agents + +### Get Agent Details +GET /api/agents/{agentId} +Returns agent profile, manager info, and direct reports. + +### List Company Goals +GET /api/companies/{{companyId}}/goals + +### List Company Projects +GET /api/companies/{{companyId}}/projects + +### Get Your Performance Metrics +GET /api/agents/me/metrics diff --git a/src/main/prompt-builder/api-docs/approvals.md b/src/main/prompt-builder/api-docs/approvals.md new file mode 100644 index 00000000..03c45c7d --- /dev/null +++ b/src/main/prompt-builder/api-docs/approvals.md @@ -0,0 +1,28 @@ +### Request an Approval (when you need human/executive permission) +POST /api/companies/{{companyId}}/approvals +Body: { + "type": "secret_access|hire_agent|approve_ceo_strategy|dangerous_command", + "relatedTaskId": "{taskId — what task is this for}", + "requestedByAgentId": "{{agentId}}", + "payloadSummary": "Clear description of what you need and why", + "impactSummary": "What happens if this is approved vs denied" +} +Approval types: + - secret_access: Need API keys, credentials, or account access + - hire_agent: Proposing a new team member + - approve_ceo_strategy: CEO submitting org strategy for Board review + - dangerous_command: Irreversible action that needs human sign-off + +### Check Approval Status +GET /api/approvals/{approvalId} + +### List Company Approvals +GET /api/companies/{{companyId}}/approvals?requestedByAgentId={{agentId}}&state=pending,approved,revision_requested + +### Comment on Approvals +POST /api/approvals/{approvalId}/comments +Body: { "body": "Your comment text. Use @AgentName to notify specific agents." } + +### Resubmit Approval After Revision Request +POST /api/approvals/{approvalId}/resubmit +Only available when approval state is "revision_requested". Resets to "pending" for re-review. diff --git a/src/main/prompt-builder/api-docs/files.md b/src/main/prompt-builder/api-docs/files.md new file mode 100644 index 00000000..27625baa --- /dev/null +++ b/src/main/prompt-builder/api-docs/files.md @@ -0,0 +1,54 @@ +### Create a Document +POST /api/companies/{{companyId}}/documents +Body: { + "type": "prd|technical_spec|design_doc|test_plan|post_mortem|meeting_notes|budget_proposal|hiring_requisition|status_report|incident_report|architecture_decision|knowledge_article", + "title": "Document title", + "content": "Full document content in markdown", + "reviewerAgentId": "{optionalReviewerAgentId}", + "projectId": "{optionalProjectId}", + "goalId": "{optionalGoalId}", + "status": "draft" +} + +### List Company Documents +GET /api/companies/{{companyId}}/documents + +### Update Document (with conflict detection) +PATCH /api/companies/{{companyId}}/documents/{documentId} +Body: { + "status": "draft|in_review|approved|archived|superseded", + "content": "Updated content (creates a revision)", + "changeSummary": "Brief description of what changed", + "baseRevisionId": "{latestRevisionId for conflict detection — omit on status-only updates}" +} +Use after reviewing a document: set to "approved" if quality meets standards, "in_review" when under review, or back to "draft" if revisions are needed. +When updating content, provide baseRevisionId from the document's latestRevisionId to detect conflicts. + +### List Document Revisions +GET /api/companies/{{companyId}}/documents/{documentId}/revisions + +### Work Products (Structured Deliverables) +POST /api/issues/{issueId}/work-products +Body: { + "type": "pull_request|branch|commit|artifact|document|preview_url|runtime_service", + "provider": "agentcompany|github|custom", + "title": "Work product title", + "url": "https://... (optional)", + "status": "active|ready_for_review|approved|merged|closed|failed|draft", + "reviewState": "none|needs_board_review|approved|changes_requested", + "isPrimary": true, + "summary": "Brief description of the deliverable" +} +Use to register structured deliverables (PRs, artifacts, deployed services) on a task. + +GET /api/issues/{issueId}/work-products +PATCH /api/work-products/{id} with partial updates (e.g. {"reviewState": "approved"}) +DELETE /api/work-products/{id} + +### Link Document to Task (Semantic Classification) +PUT /api/issues/{issueId}/documents/{key} +Body: { "documentId": "{existingDocumentId}" } +Key must be lowercase alphanumeric with _ or - (e.g. "plan", "spec", "design", "test-plan"). +Links a document to a task under a semantic key. One document per key per task. + +GET /api/issues/{issueId}/documents — list all linked documents for a task diff --git a/src/main/prompt-builder/api-docs/goals-projects.md b/src/main/prompt-builder/api-docs/goals-projects.md new file mode 100644 index 00000000..62689a26 --- /dev/null +++ b/src/main/prompt-builder/api-docs/goals-projects.md @@ -0,0 +1,21 @@ +### Create a Goal +POST /api/companies/{{companyId}}/goals +Body: { + "title": "Goal title — measurable outcome", + "description": "Definition of done — specific success criteria", + "parentId": "{optionalParentGoalId}", + "ownerAgentId": "{agentId who owns this goal}", + "status": "active" +} +Goals are top-level strategic objectives. Decompose goals into projects, then projects into tasks. + +### Create a Project +POST /api/companies/{{companyId}}/projects +Body: { + "name": "Project name", + "description": "Project scope and deliverables", + "goalId": "{goalId — which goal does this serve}", + "leadAgentId": "{agentId — who leads this project}", + "status": "planned" +} +Projects group related tasks under a goal. Assign a lead who owns delivery. diff --git a/src/main/prompt-builder/api-docs/header.md b/src/main/prompt-builder/api-docs/header.md new file mode 100644 index 00000000..53c2bc40 --- /dev/null +++ b/src/main/prompt-builder/api-docs/header.md @@ -0,0 +1,53 @@ +# AgentCompany API +You have access to the AgentCompany API to manage your work. Base URL: {{apiUrl}} +Use the environment variables AGENT_COMPANY_API_URL and AGENT_COMPANY_API_KEY for authenticated calls. +Do not print or echo AGENT_COMPANY_API_KEY into comments, summaries, or external tools. + +## Authentication & Request Format +Every API call MUST include these headers: + Authorization: Bearer $AGENT_COMPANY_API_KEY + Content-Type: application/json; charset=utf-8 + X-Agent-Company-Run-Id: {{runId}} + +Prefer Node.js fetch() over curl so non-ASCII bodies (Chinese, Japanese, etc.) are transmitted +correctly across all platforms. When curl is the only option, write the JSON body to a temp +file first and pass it via `-d @file` (shown in the POST example below). + +Example using fetch (Node.js) — PREFERRED: + const res = await fetch(`${process.env.AGENT_COMPANY_API_URL}/api/agents/me`, { + headers: { + "Authorization": `Bearer ${process.env.AGENT_COMPANY_API_KEY}`, + "Content-Type": "application/json; charset=utf-8", + "X-Agent-Company-Run-Id": "{{runId}}" + } + }); + const data = await res.json(); + +Example POST using fetch (Node.js) — PREFERRED for non-ASCII content: + const res = await fetch(`${process.env.AGENT_COMPANY_API_URL}/api/companies/{{companyId}}/issues`, { + method: "POST", + headers: { + "Authorization": `Bearer ${process.env.AGENT_COMPANY_API_KEY}`, + "Content-Type": "application/json; charset=utf-8", + "X-Agent-Company-Run-Id": "{{runId}}" + }, + body: JSON.stringify({title:"Task title",description:"Details",assigneeAgentId:"agent-id",priority:"medium",status:"todo"}) + }); + +Example GET using curl: + curl -s -X GET "$AGENT_COMPANY_API_URL/api/agents/me" \ + -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \ + -H "Content-Type: application/json; charset=utf-8" \ + -H "X-Agent-Company-Run-Id: {{runId}}" + +Example POST using curl (write body to temp file to avoid encoding issues): + echo '{"title":"Task title","description":"Details","priority":"medium","status":"todo"}' > /tmp/body.json + curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/{{companyId}}/issues" \ + -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \ + -H "Content-Type: application/json; charset=utf-8" \ + -H "X-Agent-Company-Run-Id: {{runId}}" \ + -d @/tmp/body.json + +IMPORTANT: Always check the HTTP response status. 200/201 = success, 4xx = client error (read the error message), 5xx = server error (retry once then report). + +## Available Endpoints diff --git a/src/main/prompt-builder/api-docs/knowledge.md b/src/main/prompt-builder/api-docs/knowledge.md new file mode 100644 index 00000000..1405c4a7 --- /dev/null +++ b/src/main/prompt-builder/api-docs/knowledge.md @@ -0,0 +1,13 @@ +### Add Knowledge Entry (lessons learned, best practices) +POST /api/companies/{{companyId}}/knowledge +Body: { + "category": "lesson_learned|best_practice|decision|process|technical|business|onboarding|incident", + "topic": "What we learned", + "content": "Detailed description of the knowledge", + "importance": "high|medium|low", + "referencedEntityType": "task|project|goal", + "referencedEntityId": "{optionalEntityId}" +} + +### List Knowledge Base +GET /api/companies/{{companyId}}/knowledge diff --git a/src/main/prompt-builder/api-docs/meetings.md b/src/main/prompt-builder/api-docs/meetings.md new file mode 100644 index 00000000..d39f5733 --- /dev/null +++ b/src/main/prompt-builder/api-docs/meetings.md @@ -0,0 +1,19 @@ +### Schedule a Meeting +POST /api/companies/{{companyId}}/meetings +Body: { + "type": "standup|sprint_planning|sprint_review|retrospective|one_on_one|all_hands|department_sync|incident_review|hiring_committee|budget_review", + "title": "Meeting title", + "participantAgentIds": "Serialized JSON array of agent ids", + "scheduledAt": "ISO 8601 datetime", + "durationMinutes": 30, + "agendaJson": "Serialized JSON array of agenda items" +} + +### Update Meeting (add notes, decisions) +PATCH /api/meetings/{meetingId} +Body: { + "notesJson": "Serialized JSON array of meeting notes", + "decisionsJson": "Serialized JSON array of decisions", + "actionItemsJson": "Serialized JSON array of action items", + "status": "completed" +} diff --git a/src/main/prompt-builder/api-docs/messages.md b/src/main/prompt-builder/api-docs/messages.md new file mode 100644 index 00000000..4c53d957 --- /dev/null +++ b/src/main/prompt-builder/api-docs/messages.md @@ -0,0 +1,32 @@ +### Send a Message to Another Agent +POST /api/companies/{{companyId}}/messages +Body: { + "toAgentId": "{targetAgentId or null for non-direct channels}", + "channel": "direct|department|company|project|incident", + "channelTargetId": "{see below}", + "subject": "Message subject — clear and actionable", + "body": "Your message content — include context so recipient can act", + "priority": "urgent|normal|low", + "parentMessageId": "{optionalReplyToMessageId}" +} +channelTargetId rules: + - channel "direct": set channelTargetId to null, set toAgentId to recipient + - channel "department": set channelTargetId to department name (e.g. "engineering") + - channel "company": set channelTargetId to null + - channel "project": set channelTargetId to the project ID + - channel "incident": set channelTargetId to null +Direct messages WAKE the recipient immediately. Use this when you need another agent to act. +Department messages wake all members of that department. +Company-wide messages wake the CEO. Incident messages are visible company-wide. +Example — send urgent message to a peer: + curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/{{companyId}}/messages" \ + -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \ + -H "Content-Type: application/json" \ + -H "X-Agent-Company-Run-Id: {{runId}}" \ + -d '{"toAgentId":"PEER_ID","channel":"direct","subject":"Need API spec for integration","body":"I am working on task X and need the API contract from your team. Can you share or create a document?","priority":"urgent"}' + +### List Your Messages +GET /api/companies/{{companyId}}/messages?unreadOnly=true&limit=20 + +### Mark Message as Read +POST /api/companies/{{companyId}}/messages/{messageId}/read diff --git a/src/main/prompt-builder/api-docs/sprints.md b/src/main/prompt-builder/api-docs/sprints.md new file mode 100644 index 00000000..4ee75902 --- /dev/null +++ b/src/main/prompt-builder/api-docs/sprints.md @@ -0,0 +1,14 @@ +### List Sprints +GET /api/companies/{{companyId}}/sprints + +### Create Sprint +POST /api/companies/{{companyId}}/sprints +Body: { + "name": "Sprint 1", + "goal": "Sprint goal description", + "startDate": "ISO 8601 start date", + "endDate": "ISO 8601 end date (typically 2 weeks after start)", + "status": "planning|active|review|completed|cancelled", + "velocityPoints": 0, + "completedPoints": 0 +} diff --git a/src/main/prompt-builder/api-docs/tasks.md b/src/main/prompt-builder/api-docs/tasks.md new file mode 100644 index 00000000..e2f7e9cc --- /dev/null +++ b/src/main/prompt-builder/api-docs/tasks.md @@ -0,0 +1,69 @@ +### List Tasks +GET /api/companies/{{companyId}}/issues +Query parameters (all optional, combine as needed): + ?assigneeAgentId={{agentId}} — filter to your tasks + ?status=todo,in_progress,blocked — filter by status (comma-separated) + ?priority=critical,high — filter by priority + ?projectId=PROJ_ID — filter by project +Returns an array of task objects. Use this to find work, check on reports, or audit progress. + +### Create a Task +POST /api/companies/{{companyId}}/issues +Body: { + "title": "Task title — be specific and actionable", + "description": "Detailed description with acceptance criteria", + "assigneeAgentId": "{agentId to assign to}", + "parentId": "{parentIssueId — for subtasks}", + "projectId": "{projectId — for traceability}", + "goalId": "{goalId — for strategic alignment}", + "priority": "critical|high|medium|low", + "status": "todo" +} +Always set parentId when creating subtasks. Always set projectId and goalId when available. +Example: Create a task assigned to a report: + curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/{{companyId}}/issues" \ + -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \ + -H "Content-Type: application/json" \ + -H "X-Agent-Company-Run-Id: {{runId}}" \ + -d '{"title":"Implement user auth","description":"Build JWT-based auth with refresh tokens. Acceptance: login, logout, token refresh all work.","assigneeAgentId":"REPORT_ID","projectId":"PROJ_ID","goalId":"GOAL_ID","priority":"high","status":"todo"}' + +### Update a Task +PATCH /api/issues/{issueId} +Body (all fields optional): { + "status": "done", + "comment": "What was accomplished or what needs to change", + "title": "Updated title", + "description": "Updated description", + "priority": "critical|high|medium|low", + "assigneeAgentId": "new-assignee-id or null to unassign" +} +Changing assigneeAgentId will reassign the task and wake the new assignee. +Changing priority re-prioritizes the task in the queue. +Valid statuses: backlog, todo, in_progress, in_review, done, blocked, cancelled +ALWAYS include a "comment" when changing status — explain WHY. +Example — approve reviewed work: + curl -s -X PATCH "$AGENT_COMPANY_API_URL/api/issues/ISSUE_ID" \ + -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \ + -H "Content-Type: application/json" \ + -H "X-Agent-Company-Run-Id: {{runId}}" \ + -d '{"status":"done","comment":"Reviewed and approved. Implementation meets acceptance criteria."}' +Example — request changes: + curl -s -X PATCH "$AGENT_COMPANY_API_URL/api/issues/ISSUE_ID" \ + -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \ + -H "Content-Type: application/json" \ + -H "X-Agent-Company-Run-Id: {{runId}}" \ + -d '{"status":"in_progress","comment":"Needs changes: 1) Add error handling for edge case X. 2) Unit test coverage is below threshold."}' + +### Checkout a Task (claim it before working) +POST /api/issues/{issueId}/checkout +Body: { "agentId": "{{agentId}}" } +Returns 409 if already claimed by another agent. You MUST checkout before starting work. + +### Add Comment (communicate on a task) +POST /api/issues/{issueId}/comments +Body: { "body": "Your message — be specific and actionable" } +Use comments for: progress updates, asking questions, providing feedback, escalating blockers. + +### Read Comments on a Task +GET /api/issues/{issueId}/comments +Returns all comments in chronological order. Read ALL comments before taking action on a task. diff --git a/src/main/prompt-builder/api-section.ts b/src/main/prompt-builder/api-section.ts index 390e08ae..cfac7a9c 100644 --- a/src/main/prompt-builder/api-section.ts +++ b/src/main/prompt-builder/api-section.ts @@ -1,366 +1,44 @@ import type { PromptContext } from "./index"; import { buildSocialSection } from "./api-endpoints"; +import headerMd from "./api-docs/header.md?raw"; +import agentControlMd from "./api-docs/agent-control.md?raw"; +import tasksMd from "./api-docs/tasks.md?raw"; +import goalsProjectsMd from "./api-docs/goals-projects.md?raw"; +import approvalsMd from "./api-docs/approvals.md?raw"; +import messagesMd from "./api-docs/messages.md?raw"; +import filesMd from "./api-docs/files.md?raw"; +import knowledgeMd from "./api-docs/knowledge.md?raw"; +import meetingsMd from "./api-docs/meetings.md?raw"; +import agentsMd from "./api-docs/agents.md?raw"; +import sprintsMd from "./api-docs/sprints.md?raw"; + +const API_DOC_SECTIONS: string[] = [ + headerMd, + agentControlMd, + tasksMd, + goalsProjectsMd, + approvalsMd, + messagesMd, + filesMd, + knowledgeMd, + meetingsMd, + agentsMd, + sprintsMd, +]; + +function render(template: string, ctx: PromptContext): string { + const connectorIds = ctx.allConnectors && ctx.allConnectors.length > 0 + ? ctx.allConnectors.map((c) => c.id).join("|") + : "claude_local"; + return template + .replace(/\{\{apiUrl\}\}/g, ctx.apiUrl) + .replace(/\{\{companyId\}\}/g, ctx.agent.companyId) + .replace(/\{\{agentId\}\}/g, ctx.agent.id) + .replace(/\{\{runId\}\}/g, ctx.runId) + .replace(/\{\{connectorIds\}\}/g, connectorIds); +} export function buildAPISection(ctx: PromptContext): string { - return `# AgentCompany API -You have access to the AgentCompany API to manage your work. Base URL: ${ctx.apiUrl} -Use the environment variables AGENT_COMPANY_API_URL and AGENT_COMPANY_API_KEY for authenticated calls. -Do not print or echo AGENT_COMPANY_API_KEY into comments, summaries, or external tools. - -## Authentication & Request Format -Every API call MUST include these headers: - Authorization: Bearer $AGENT_COMPANY_API_KEY - Content-Type: application/json; charset=utf-8 - X-Agent-Company-Run-Id: ${ctx.runId} - -Prefer Node.js fetch() over curl so non-ASCII bodies (Chinese, Japanese, etc.) are transmitted -correctly across all platforms. When curl is the only option, write the JSON body to a temp -file first and pass it via \`-d @file\` (shown in the POST example below). - -Example using fetch (Node.js) — PREFERRED: - const res = await fetch(\`\${process.env.AGENT_COMPANY_API_URL}/api/agents/me\`, { - headers: { - "Authorization": \`Bearer \${process.env.AGENT_COMPANY_API_KEY}\`, - "Content-Type": "application/json; charset=utf-8", - "X-Agent-Company-Run-Id": "${ctx.runId}" - } - }); - const data = await res.json(); - -Example POST using fetch (Node.js) — PREFERRED for non-ASCII content: - const res = await fetch(\`\${process.env.AGENT_COMPANY_API_URL}/api/companies/${ctx.agent.companyId}/issues\`, { - method: "POST", - headers: { - "Authorization": \`Bearer \${process.env.AGENT_COMPANY_API_KEY}\`, - "Content-Type": "application/json; charset=utf-8", - "X-Agent-Company-Run-Id": "${ctx.runId}" - }, - body: JSON.stringify({title:"Task title",description:"Details",assigneeAgentId:"agent-id",priority:"medium",status:"todo"}) - }); - -Example GET using curl: - curl -s -X GET "$AGENT_COMPANY_API_URL/api/agents/me" \\ - -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \\ - -H "Content-Type: application/json; charset=utf-8" \\ - -H "X-Agent-Company-Run-Id: ${ctx.runId}" - -Example POST using curl (write body to temp file to avoid encoding issues): - echo '{"title":"Task title","description":"Details","priority":"medium","status":"todo"}' > /tmp/body.json - curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/${ctx.agent.companyId}/issues" \\ - -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \\ - -H "Content-Type: application/json; charset=utf-8" \\ - -H "X-Agent-Company-Run-Id: ${ctx.runId}" \\ - -d @/tmp/body.json - -IMPORTANT: Always check the HTTP response status. 200/201 = success, 4xx = client error (read the error message), 5xx = server error (retry once then report). - -## Available Endpoints - -### Get Your Identity -GET /api/agents/me -Returns your agent record with chain of command, budget info, department, and status. -Call this first to confirm your identity and understand your position. - -### Get Your Standup Briefing (RECOMMENDED — call this first every wake) -GET /api/agents/me/standup -Returns a comprehensive summary: tasks awaiting your review, blocked tasks, -recent comments, pending approvals, report statuses. Use this to prioritize your work. -This is the SINGLE MOST IMPORTANT call each wake — it tells you exactly what needs attention. - -### List Tasks -GET /api/companies/${ctx.agent.companyId}/issues -Query parameters (all optional, combine as needed): - ?assigneeAgentId=${ctx.agent.id} — filter to your tasks - ?status=todo,in_progress,blocked — filter by status (comma-separated) - ?priority=critical,high — filter by priority - ?projectId=PROJ_ID — filter by project -Returns an array of task objects. Use this to find work, check on reports, or audit progress. - -### Create a Task -POST /api/companies/${ctx.agent.companyId}/issues -Body: { - "title": "Task title — be specific and actionable", - "description": "Detailed description with acceptance criteria", - "assigneeAgentId": "{agentId to assign to}", - "parentId": "{parentIssueId — for subtasks}", - "projectId": "{projectId — for traceability}", - "goalId": "{goalId — for strategic alignment}", - "priority": "critical|high|medium|low", - "status": "todo" -} -Always set parentId when creating subtasks. Always set projectId and goalId when available. -Example: Create a task assigned to a report: - curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/${ctx.agent.companyId}/issues" \\ - -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \\ - -H "Content-Type: application/json" \\ - -H "X-Agent-Company-Run-Id: ${ctx.runId}" \\ - -d '{"title":"Implement user auth","description":"Build JWT-based auth with refresh tokens. Acceptance: login, logout, token refresh all work.","assigneeAgentId":"REPORT_ID","projectId":"PROJ_ID","goalId":"GOAL_ID","priority":"high","status":"todo"}' - -### Update a Task -PATCH /api/issues/{issueId} -Body (all fields optional): { - "status": "done", - "comment": "What was accomplished or what needs to change", - "title": "Updated title", - "description": "Updated description", - "priority": "critical|high|medium|low", - "assigneeAgentId": "new-assignee-id or null to unassign" -} -Changing assigneeAgentId will reassign the task and wake the new assignee. -Changing priority re-prioritizes the task in the queue. -Valid statuses: backlog, todo, in_progress, in_review, done, blocked, cancelled -ALWAYS include a "comment" when changing status — explain WHY. -Example — approve reviewed work: - curl -s -X PATCH "$AGENT_COMPANY_API_URL/api/issues/ISSUE_ID" \\ - -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \\ - -H "Content-Type: application/json" \\ - -H "X-Agent-Company-Run-Id: ${ctx.runId}" \\ - -d '{"status":"done","comment":"Reviewed and approved. Implementation meets acceptance criteria."}' -Example — request changes: - curl -s -X PATCH "$AGENT_COMPANY_API_URL/api/issues/ISSUE_ID" \\ - -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \\ - -H "Content-Type: application/json" \\ - -H "X-Agent-Company-Run-Id: ${ctx.runId}" \\ - -d '{"status":"in_progress","comment":"Needs changes: 1) Add error handling for edge case X. 2) Unit test coverage is below threshold."}' - -### Checkout a Task (claim it before working) -POST /api/issues/{issueId}/checkout -Body: { "agentId": "${ctx.agent.id}" } -Returns 409 if already claimed by another agent. You MUST checkout before starting work. - -### Add Comment (communicate on a task) -POST /api/issues/{issueId}/comments -Body: { "body": "Your message — be specific and actionable" } -Use comments for: progress updates, asking questions, providing feedback, escalating blockers. - -### Read Comments on a Task -GET /api/issues/{issueId}/comments -Returns all comments in chronological order. Read ALL comments before taking action on a task. - -### Create a Goal -POST /api/companies/${ctx.agent.companyId}/goals -Body: { - "title": "Goal title — measurable outcome", - "description": "Definition of done — specific success criteria", - "parentId": "{optionalParentGoalId}", - "ownerAgentId": "{agentId who owns this goal}", - "status": "active" -} -Goals are top-level strategic objectives. Decompose goals into projects, then projects into tasks. - -### Create a Project -POST /api/companies/${ctx.agent.companyId}/projects -Body: { - "name": "Project name", - "description": "Project scope and deliverables", - "goalId": "{goalId — which goal does this serve}", - "leadAgentId": "{agentId — who leads this project}", - "status": "planned" -} -Projects group related tasks under a goal. Assign a lead who owns delivery. - -### Request an Approval (when you need human/executive permission) -POST /api/companies/${ctx.agent.companyId}/approvals -Body: { - "type": "secret_access|hire_agent|approve_ceo_strategy|dangerous_command", - "relatedTaskId": "{taskId — what task is this for}", - "requestedByAgentId": "${ctx.agent.id}", - "payloadSummary": "Clear description of what you need and why", - "impactSummary": "What happens if this is approved vs denied" -} -Approval types: - - secret_access: Need API keys, credentials, or account access - - hire_agent: Proposing a new team member - - approve_ceo_strategy: CEO submitting org strategy for Board review - - dangerous_command: Irreversible action that needs human sign-off - -### Check Approval Status -GET /api/approvals/{approvalId} - -### List Company Approvals -GET /api/companies/${ctx.agent.companyId}/approvals?requestedByAgentId=${ctx.agent.id}&state=pending,approved,revision_requested - -### Send a Message to Another Agent -POST /api/companies/${ctx.agent.companyId}/messages -Body: { - "toAgentId": "{targetAgentId or null for non-direct channels}", - "channel": "direct|department|company|project|incident", - "channelTargetId": "{see below}", - "subject": "Message subject — clear and actionable", - "body": "Your message content — include context so recipient can act", - "priority": "urgent|normal|low", - "parentMessageId": "{optionalReplyToMessageId}" -} -channelTargetId rules: - - channel "direct": set channelTargetId to null, set toAgentId to recipient - - channel "department": set channelTargetId to department name (e.g. "engineering") - - channel "company": set channelTargetId to null - - channel "project": set channelTargetId to the project ID - - channel "incident": set channelTargetId to null -Direct messages WAKE the recipient immediately. Use this when you need another agent to act. -Department messages wake all members of that department. -Company-wide messages wake the CEO. Incident messages are visible company-wide. -Example — send urgent message to a peer: - curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/${ctx.agent.companyId}/messages" \\ - -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \\ - -H "Content-Type: application/json" \\ - -H "X-Agent-Company-Run-Id: ${ctx.runId}" \\ - -d '{"toAgentId":"PEER_ID","channel":"direct","subject":"Need API spec for integration","body":"I am working on task X and need the API contract from your team. Can you share or create a document?","priority":"urgent"}' - -### List Your Messages -GET /api/companies/${ctx.agent.companyId}/messages?unreadOnly=true&limit=20 - -### Mark Message as Read -POST /api/companies/${ctx.agent.companyId}/messages/{messageId}/read - -### Create a Document -POST /api/companies/${ctx.agent.companyId}/documents -Body: { - "type": "prd|technical_spec|design_doc|test_plan|post_mortem|meeting_notes|budget_proposal|hiring_requisition|status_report|incident_report|architecture_decision|knowledge_article", - "title": "Document title", - "content": "Full document content in markdown", - "reviewerAgentId": "{optionalReviewerAgentId}", - "projectId": "{optionalProjectId}", - "goalId": "{optionalGoalId}", - "status": "draft" -} - -### List Company Documents -GET /api/companies/${ctx.agent.companyId}/documents - -### Update Document (with conflict detection) -PATCH /api/companies/${ctx.agent.companyId}/documents/{documentId} -Body: { - "status": "draft|in_review|approved|archived|superseded", - "content": "Updated content (creates a revision)", - "changeSummary": "Brief description of what changed", - "baseRevisionId": "{latestRevisionId for conflict detection — omit on status-only updates}" -} -Use after reviewing a document: set to "approved" if quality meets standards, "in_review" when under review, or back to "draft" if revisions are needed. -When updating content, provide baseRevisionId from the document's latestRevisionId to detect conflicts. - -### List Document Revisions -GET /api/companies/${ctx.agent.companyId}/documents/{documentId}/revisions - -### Comment on Approvals -POST /api/approvals/{approvalId}/comments -Body: { "body": "Your comment text. Use @AgentName to notify specific agents." } - -### Resubmit Approval After Revision Request -POST /api/approvals/{approvalId}/resubmit -Only available when approval state is "revision_requested". Resets to "pending" for re-review. - -### Work Products (Structured Deliverables) -POST /api/issues/{issueId}/work-products -Body: { - "type": "pull_request|branch|commit|artifact|document|preview_url|runtime_service", - "provider": "agentcompany|github|custom", - "title": "Work product title", - "url": "https://... (optional)", - "status": "active|ready_for_review|approved|merged|closed|failed|draft", - "reviewState": "none|needs_board_review|approved|changes_requested", - "isPrimary": true, - "summary": "Brief description of the deliverable" -} -Use to register structured deliverables (PRs, artifacts, deployed services) on a task. - -GET /api/issues/{issueId}/work-products -PATCH /api/work-products/{id} with partial updates (e.g. {"reviewState": "approved"}) -DELETE /api/work-products/{id} - -### Link Document to Task (Semantic Classification) -PUT /api/issues/{issueId}/documents/{key} -Body: { "documentId": "{existingDocumentId}" } -Key must be lowercase alphanumeric with _ or - (e.g. "plan", "spec", "design", "test-plan"). -Links a document to a task under a semantic key. One document per key per task. - -GET /api/issues/{issueId}/documents — list all linked documents for a task - -### Add Knowledge Entry (lessons learned, best practices) -POST /api/companies/${ctx.agent.companyId}/knowledge -Body: { - "category": "lesson_learned|best_practice|decision|process|technical|business|onboarding|incident", - "topic": "What we learned", - "content": "Detailed description of the knowledge", - "importance": "high|medium|low", - "referencedEntityType": "task|project|goal", - "referencedEntityId": "{optionalEntityId}" -} - -### List Knowledge Base -GET /api/companies/${ctx.agent.companyId}/knowledge - -### Schedule a Meeting -POST /api/companies/${ctx.agent.companyId}/meetings -Body: { - "type": "standup|sprint_planning|sprint_review|retrospective|one_on_one|all_hands|department_sync|incident_review|hiring_committee|budget_review", - "title": "Meeting title", - "participantAgentIds": "Serialized JSON array of agent ids", - "scheduledAt": "ISO 8601 datetime", - "durationMinutes": 30, - "agendaJson": "Serialized JSON array of agenda items" -} - -### Update Meeting (add notes, decisions) -PATCH /api/meetings/{meetingId} -Body: { - "notesJson": "Serialized JSON array of meeting notes", - "decisionsJson": "Serialized JSON array of decisions", - "actionItemsJson": "Serialized JSON array of action items", - "status": "completed" -} - -### Propose a Hire -POST /api/companies/${ctx.agent.companyId}/agents -Body: { - "name": "New hire display name (must not repeat role/title)", - "role": "role_title", - "title": "Descriptive title", - "department": "engineering|product|marketing|sales|hr|finance|legal|operations|customer_support|research|design|executive", - "reportsTo": "{managerAgentId — who this person reports to}", - "connectorId": "${ctx.allConnectors && ctx.allConnectors.length > 0 ? ctx.allConnectors.map((c) => c.id).join("|") : "claude_local"}", - "workspaceId": "{optionalWorkspaceId}", - "model": "model-identifier", - "capabilities": "Detailed description of what this hire should own and be able to do", - "budgetMonthlyUsd": 250 -} -This creates the agent in pending_approval state. The Board (human operator) must approve. -After approval, the agent becomes active and can be assigned work. - -### Wake Another Agent -POST /api/agents/{agentId}/wake -Body: { "reason": "Brief reason for waking them" } -Use this when you need another agent to take action NOW. This triggers their next heartbeat. - -### List All Agents -GET /api/companies/${ctx.agent.companyId}/agents - -### Get Agent Details -GET /api/agents/{agentId} -Returns agent profile, manager info, and direct reports. - -### List Company Goals -GET /api/companies/${ctx.agent.companyId}/goals - -### List Company Projects -GET /api/companies/${ctx.agent.companyId}/projects - -### Get Your Performance Metrics -GET /api/agents/me/metrics - -### List Sprints -GET /api/companies/${ctx.agent.companyId}/sprints - -### Create Sprint -POST /api/companies/${ctx.agent.companyId}/sprints -Body: { - "name": "Sprint 1", - "goal": "Sprint goal description", - "startDate": "ISO 8601 start date", - "endDate": "ISO 8601 end date (typically 2 weeks after start)", - "status": "planning|active|review|completed|cancelled", - "velocityPoints": 0, - "completedPoints": 0 -} -${buildSocialSection(ctx)}`; + const body = API_DOC_SECTIONS.map((s) => render(s, ctx).trimEnd()).join("\n\n"); + return `${body}\n${buildSocialSection(ctx)}`; }