Skip to content

Agent Task Contract

An Agent Task is the unit of work the Control Plane assigns and the Agent Mesh executes. The task contract is structured so that any agent is interchangeable, every execution is observable, and every produced artifact is traceable to the task, agent, skill, and context that created it.

Task assignment

{
  "taskId": "task-4d21",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "workflowInstanceId": "wf-7781",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40",
  "agentRole": "SolutionArchitect",
  "requestedSkill": "ConnectSoft.Skill.DesignServiceBlueprint",
  "inputs": {
    "intent": "Design the reservations service blueprint",
    "blueprintId": "bp-service-reservations",
    "inputArtifacts": ["art-domainmodel-7c", "art-contextmap-3"]
  },
  "contextRequest": {
    "scope": ["project", "boundedContext:Reservations"],
    "tokenBudget": 16000
  },
  "constraints": {
    "modelPolicyId": "mp-architecture-default",
    "maxCorrectionAttempts": 2,
    "deadline": "2026-06-11T00:30:00Z"
  },
  "createdAt": "2026-06-11T00:00:00Z",
  "status": "Assigned"
}

Execution result

{
  "executionId": "exec-8841",
  "taskId": "task-4d21",
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "agentVersion": "3.2.0",
  "contextPackageId": "ctx-31f8",
  "skillExecutions": ["skx-1"],
  "modelInvocations": ["mdl-1", "mdl-2"],
  "toolInvocations": ["tool-1"],
  "outputArtifacts": ["art-serviceblueprint-reservations-1"],
  "validation": {
    "validationResultId": "val-22",
    "passed": true,
    "rules": ["schema", "naming", "dependency", "policy"]
  },
  "emittedEvents": ["AgentTaskCompleted", "ArtifactCreated"],
  "tokensUsed": 14210,
  "startedAt": "2026-06-11T00:01:00Z",
  "completedAt": "2026-06-11T00:04:30Z",
  "status": "Completed"
}

Lifecycle

stateDiagram-v2
    [*] --> Assigned
    Assigned --> ContextLoading: agent claims task
    ContextLoading --> Executing: ContextPackage ready
    Executing --> Validating: artifacts produced
    Validating --> Completed: validation passed
    Validating --> Correcting: validation failed
    Correcting --> Validating: corrected (attempt <= max)
    Correcting --> Failed: max attempts exceeded
    Executing --> Failed: unrecoverable error
    Completed --> [*]
    Failed --> [*]
Hold "Alt" / "Option" to enable pan & zoom
State Meaning Emits
Assigned Task placed by TaskAssignmentService. AgentTaskAssigned
ContextLoading Agent requests a context package. —
Executing Skill runs, model/tool invocations occur. AgentExecutionStarted
Validating Outputs checked by AgentValidationService. —
Correcting AgentCorrectionService retries with feedback. CorrectionAttempted
Completed Validated artifacts registered. AgentTaskCompleted, ArtifactCreated
Failed Escalated to human review or retried by workflow. AgentTaskFailed

Contract rules

  1. Idempotent assignment — re-delivering an Assigned task with the same taskId does not create a duplicate execution.
  2. Context-grounded — execution must consume a Context Package; the contextPackageId is recorded for traceability and improvement attribution.
  3. Validated output — no artifact is registered until AgentValidationService passes it against schema, naming, dependency, and policy rules.
  4. Bounded correction — maxCorrectionAttempts caps self-correction; exceeding it fails the task to human escalation in the Human Review Center.
  5. Full emission — every state transition emits an event in the canonical envelope so the lifecycle is replayable.