Skip to content

HTTP_API.md

Latest commit

 

History

History
254 lines (187 loc) · 6 KB

HTTP_API.md

File metadata and controls

254 lines (187 loc) · 6 KB
Raw

AgentCore HTTP API

The AgentCore HTTP API is the first network-accessible interface for the local coding-agent platform. It is intentionally small: one process, in-memory state, JSON commands, Server-Sent Events for task execution traces, and explicit proposal approval.

This is not a production deployment layer yet. The default bind host is 127.0.0.1, there is no authentication, and state is not durable.

Lifecycle

  1. Start the server with a runtime configuration.
  2. Create an agent bound to a workspace.
  3. Create a task for that agent.
  4. Request a plan proposal for the task.
  5. Inspect the proposed action plan and approval requirements.
  6. Approve or reject explicitly.
  7. Execute only an approved mutating proposal.
  8. Consume task events through SSE.
  9. Inspect the final task report and Git diff.

Execution never implies approval, and no Git commit is created automatically.

Launch

python scripts/agentcore_server.py \
  --config config/sglang-a100.yaml \
  --host 127.0.0.1 \
  --port 8080

Useful options:

  • --workspace-root PATH: default parent directory for server-created workspaces.
  • --warmup: warm up the runtime on startup.
  • --no-warmup: skip runtime warmup.

Endpoints

Health:

GET /health

Agents:

POST   /v1/agents
GET    /v1/agents
GET    /v1/agents/{agent_id}
DELETE /v1/agents/{agent_id}

Tasks:

POST /v1/agents/{agent_id}/tasks
GET  /v1/tasks/{task_id}
GET  /v1/tasks/{task_id}/report

Planning:

POST /v1/tasks/{task_id}/proposals
POST /v1/tasks/{task_id}/proposals/stream
GET  /v1/proposals/{proposal_id}
POST /v1/proposals/{proposal_id}/approve
POST /v1/proposals/{proposal_id}/reject

Execution:

POST /v1/proposals/{proposal_id}/execute
POST /v1/tasks/{task_id}/cancel

Workspace inspection:

GET /v1/agents/{agent_id}/git/status
GET /v1/agents/{agent_id}/git/diff

Events:

GET /v1/tasks/{task_id}/events

Requests

Create an agent:

{
  "system_prompt": "You are a concise coding assistant.",
  "workspace_root": "workspace/project-a",
  "workspace_mode": "read_write",
  "workspace_metadata": {},
  "generation_options": {}
}

Create a task:

{
  "title": "Edit parser",
  "description": "Replace return 0 with return 1 in parser.c.",
  "metadata": {}
}

Request a proposal:

{
  "instruction": "Replace return 0 with return 1 in parser.c.",
  "max_tokens": 512,
  "temperature": 0
}

Request a streamed proposal:

POST /v1/tasks/{task_id}/proposals/stream

The request body is the same as non-streaming proposal creation. The response is an SSE stream containing user-visible assistant output first, followed by plan.proposed if the completed assistant text validates as an ActionPlan.

Reject a proposal:

{
  "reason": "The proposed file is not the intended target."
}

Approval Semantics

Proposal generation and execution are separate operations.

Mutating plans cannot execute until an explicit approval request has succeeded. Rejected proposals cannot execute. Duplicate execution requests are rejected.

The current mutating actions include file writes, text replacement, and checkpoint creation. Read-only actions such as Git status, Git diff, file reads, and task reports may execute under the default approval policy.

SSE Format

Task events and streamed proposal events are serialized as Server-Sent Events:

event: action.started
id: 7
data: {"event_type":"action.started","summary":"Action started: replace_text",...}

Events preserve the order in which AgentCore records them. The stream replays existing task history first, then follows live events. A stream closes after a terminal task execution event. During idle periods the server may send heartbeat comments:

: heartbeat

No raw chain-of-thought is exposed. Events contain only structured work state: task lifecycle, plan proposal/approval/rejection, action status, workspace modifications, checkpoints, Git diff, and final execution status.

Token Streaming

Assistant token streaming uses the same AgentEvent schema as operational events:

event: assistant.started
data: {"event_type":"assistant.started","payload":{"metadata":{"prompt_tokens":42}}}

event: assistant.delta
data: {"event_type":"assistant.delta","payload":{"delta":"visible assistant text"}}

event: assistant.completed
data: {"event_type":"assistant.completed","payload":{"text":"complete visible text","metrics":{...}}}

Only visible assistant text is streamed. Runtime-specific fields such as hidden reasoning, chain-of-thought, or backend-private deltas are not exposed.

For streamed planning, AgentCore buffers the complete visible assistant response and validates it as an ActionPlan only after assistant.completed. If validation fails, the stream emits assistant.failed and no proposal is stored.

Cancellation

Cancellation is cooperative:

POST /v1/tasks/{task_id}/cancel

Request body:

{
  "reason": "user aborted"
}

The server emits:

event: cancellation.requested
event: cancellation.completed

If the task has not started, it is marked cancelled immediately. If execution is already running, the current atomic action is allowed to finish safely and the executor stops before the next action. AgentCore does not claim that an already-running GPU request, filesystem operation, or runtime call can always be interrupted instantly.

Cancelled tasks reject new execution requests.

Security Model

This first server is intended for localhost development only:

  • default bind host is 127.0.0.1;
  • no authentication is implemented yet;
  • no arbitrary shell endpoint exists;
  • no unrestricted Git command endpoint exists;
  • no clone, fetch, pull, or push endpoint exists;
  • all workspace operations continue to use AgentCore workspace validation.

Production concerns intentionally deferred:

  • authentication and authorization;
  • durable storage;
  • multi-user isolation;
  • process supervision;
  • rate limits;
  • distributed workers;
  • remote workspace provisioning.