APIs

Target Architecture — Final-State Design

The Agent Mesh exposes a governed API surface for registering the workforce, assigning work, and driving executions. Every endpoint is multi-tenant, authorized, versioned, and emits canonical events. Resource paths follow the naming conventions: plural, hyphenated nouns with verb sub-paths for non-CRUD actions.

Surface Overview

#	Method & Path	Owner Service	Kind
1	POST /agents/register	AgentRegistryService	Public
2	GET /agents/{agentId}	AgentRegistryService	Public
3	POST /skills/register	SkillRegistryService	Public
4	POST /agent-tasks	AgentTaskService	Internal (Control Plane)
5	GET /agent-tasks/{taskId}	AgentTaskService	Public
6	POST /agent-executions	AgentExecutionService	Internal (Runtime)
7	POST /agent-executions/{executionId}/complete	AgentExecutionService	Internal (Runtime)
8	POST /agent-executions/{executionId}/fail	AgentExecutionService	Internal (Runtime)
9	GET /agents/{agentId}/health	AgentPoolManager	Public

Access Model

• Public endpoints are reachable through the factory API gateway and used by the Control Plane, Factory Studio, and operators.
• Internal endpoints (POST /agent-tasks, the agent-executions action endpoints) are restricted to in-mesh callers (the runtime and Control Plane) over the internal network and service identities.
• gRPC: high-frequency runtime calls — execution creation/completion and pool health probes — are also offered over gRPC for low-latency intra-mesh communication; the REST contracts below are the canonical shapes, with gRPC messages mirroring them field-for-field.

Authorization

Every request is authenticated with a workload identity (Azure AD / Entra) and authorized against:

• Tenant scope — tenantId claim must match the resource's tenant; cross-tenant access is rejected.
• Operation scope — caller role (registrar, orchestrator, runtime, operator) must permit the action.
• Agent permission scope — execution endpoints re-check the acting agent version's scope.

See Security for the full model.

Versioning

• APIs are versioned by header (api-version: 2026-06-01) with additive evolution; breaking changes increment the version.
• Request/response bodies tolerate unknown fields (forward compatibility).
• Resource ids are stable, prefixed identifiers per the naming conventions.

Endpoints

POST /agents/register

Registers an agent definition and an initial version. Emits AgentRegistered.

// Request
{
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "cluster": "Architecture",
  "version": "3.2.0",
  "permissionScope": {
    "tools": ["template:scaffold", "knowledge:search"],
    "modelPolicyId": "mp-architecture-default",
    "classificationCeiling": "Internal"
  },
  "skillBindings": [
    { "skillId": "ConnectSoft.Skill.DesignServiceBlueprint", "versionRange": ">=2.0.0 <3.0.0" }
  ]
}

// 201 Created
{
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "version": "3.2.0",
  "status": "Registered",
  "registeredAt": "2026-06-11T00:00:00Z"
}

GET /agents/{agentId}

Returns an agent definition with its current and available versions.

// 200 OK
{
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "cluster": "Architecture",
  "currentVersion": "3.2.0",
  "versions": ["3.0.0", "3.1.0", "3.2.0"],
  "status": "Active",
  "permissionScope": {
    "tools": ["template:scaffold", "knowledge:search"],
    "modelPolicyId": "mp-architecture-default",
    "classificationCeiling": "Internal"
  }
}

POST /skills/register

Registers a skill definition and version with its input/output contract. Emits SkillRegistered.

// Request
{
  "skillId": "ConnectSoft.Skill.DesignServiceBlueprint",
  "version": "2.1.0",
  "category": "Architecture",
  "input": { "intent": "string", "blueprintId": "string", "inputArtifacts": ["artifactRef"] },
  "output": { "outputArtifacts": ["artifactRef"], "summary": "string" },
  "tools": ["template:scaffold", "knowledge:search"],
  "validation": ["schema", "naming", "dependency", "policy"]
}

// 201 Created
{ "skillId": "ConnectSoft.Skill.DesignServiceBlueprint", "version": "2.1.0", "status": "Registered" }

POST /agent-tasks

Assigns a task to the mesh (Control Plane only). Idempotent on taskId. Emits AgentTaskAssigned.

// Request
{
  "taskId": "task-4d21",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40",
  "agentRole": "SolutionArchitect",
  "requestedSkill": "ConnectSoft.Skill.DesignServiceBlueprint",
  "inputs": { "intent": "Design the reservations service blueprint" },
  "contextRequest": { "scope": ["project", "boundedContext:Reservations"], "tokenBudget": 16000 },
  "constraints": { "modelPolicyId": "mp-architecture-default", "maxCorrectionAttempts": 2 }
}

// 202 Accepted
{ "taskId": "task-4d21", "status": "Assigned", "assignedAt": "2026-06-11T00:00:00Z" }

GET /agent-tasks/{taskId}

Returns the current task state and the latest execution reference.

// 200 OK
{
  "taskId": "task-4d21",
  "status": "Executing",
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "agentVersion": "3.2.0",
  "latestExecutionId": "exec-8841",
  "traceId": "trace-9f1c2b7d",
  "updatedAt": "2026-06-11T00:02:00Z"
}

POST /agent-executions

Starts an execution for a claimed task (runtime only). Emits AgentExecutionStarted.

// Request
{
  "taskId": "task-4d21",
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "agentVersion": "3.2.0",
  "contextPackageId": "ctx-31f8",
  "traceId": "trace-9f1c2b7d"
}

// 201 Created
{ "executionId": "exec-8841", "taskId": "task-4d21", "status": "Executing", "startedAt": "2026-06-11T00:01:00Z" }

POST /agent-executions/{executionId}/complete

Completes an execution with validated outputs. Emits AgentTaskCompleted (and ArtifactCreated per artifact).

// Request
{
  "outputArtifacts": ["art-serviceblueprint-reservations-1"],
  "validationResultId": "val-22",
  "tokensUsed": 14210
}

// 200 OK
{ "executionId": "exec-8841", "taskId": "task-4d21", "status": "Completed", "completedAt": "2026-06-11T00:04:30Z" }

POST /agent-executions/{executionId}/fail

Fails an execution after unrecoverable error or exhausted correction. Emits AgentTaskFailed.

// Request
{
  "reason": "MaxCorrectionAttemptsExceeded",
  "detail": "Validation failed on dependency rule after 2 corrections",
  "lastValidationResultId": "val-29"
}

// 200 OK
{ "executionId": "exec-8841", "taskId": "task-4d21", "status": "Failed", "failedAt": "2026-06-11T00:06:00Z", "escalated": true }

GET /agents/{agentId}/health

Returns pooled health for an agent (served from Redis hot state by the AgentPoolManager).

// 200 OK
{
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "health": "Healthy",
  "pool": { "warmInstances": 3, "busyInstances": 1, "maxConcurrency": 8 },
  "lastProbedAt": "2026-06-11T00:05:55Z"
}

Related

• Task Contracts
• Agent Registry
• Skill Registry
• Events
• API Catalog
• Naming Conventions