Technical Specification

Last Updated: 2024
Version: v1 (OpenAPI 3.0)
Status: Active

Overview:

The Agent Protocol defines a REST API that agents must expose to be compliant. The specification is formally defined using OpenAPI 3.0, ensuring precise, machine-readable documentation.

Core Concepts

1. Tasks A task represents a goal or objective you want the agent to accomplish. When you create a task, you provide the agent with:

• An input (the goal)
• Optional additional context or constraints

Example task: “Research the top 5 AI tools for sales automation and create a comparison table.”

2. Steps Each task is broken down into steps. A step represents one unit of work the agent performs toward completing the task. Steps can include:

• Actions taken by the agent
• Outputs or artifacts generated
• Status updates

3. Artifacts Artifacts are files, documents, or data produced by the agent during task execution. These can include:

• Generated code
• Reports or summaries
• Downloaded files
• Processed data

API Endpoints

Base Path: /ap/v1/agent

Create Task

http

POST /ap/v1/agent/tasks
Content-Type: application/json

{
  "input": "Your task description",
  "additional_input": {
    // Optional context
  }
}

Response:
{
  "task_id": "unique-task-identifier",
  "input": "Your task description",
  "artifacts": []
}

Execute Step

http

POST /ap/v1/agent/tasks/{task_id}/steps
Content-Type: application/json

{
  "input": "Optional step input"
}

Response:
{
  "step_id": "unique-step-identifier",
  "task_id": "task-identifier",
  "name": "Step name",
  "status": "created | running | completed",
  "output": "Step result",
  "artifacts": [],
  "is_last": false
}

List Tasks

http

GET /ap/v1/agent/tasks

Response:
{
  "tasks": [
    {
      "task_id": "...",
      "input": "...",
      "artifacts": []
    }
  ]
}

Get Task

http

GET /ap/v1/agent/tasks/{task_id}

Response:
{
  "task_id": "...",
  "input": "...",
  "artifacts": []
}

List Steps

http

GET /ap/v1/agent/tasks/{task_id}/steps

Response:
{
  "steps": [
    {
      "step_id": "...",
      "task_id": "...",
      "status": "...",
      "output": "..."
    }
  ]
}

Upload Artifact

http

POST /ap/v1/agent/tasks/{task_id}/artifacts
Content-Type: multipart/form-data

Response:
{
  "artifact_id": "...",
  "file_name": "...",
  "uri": "..."
}

Download Artifact

http

GET /ap/v1/agent/tasks/{task_id}/artifacts/{artifact_id}

Response: Binary file data

Implementation Notes

Authentication: The specification doesn’t mandate a specific authentication mechanism. Implementations can use:

• API keys
• OAuth 2.0
• JWT tokens
• Or operate without authentication for local use

Error Handling: Standard HTTP status codes should be used:

• 200 OK – Success
• 400 Bad Request – Invalid input
• 404 Not Found – Task/step not found
• 500 Internal Server Error – Agent error

CORS: Implementations should support CORS for web-based integrations.

Full OpenAPI Specification

View Complete OpenAPI Spec on GitHub →