Skip to content

Task Contracts

Target Architecture — Final-State Design

The task contract is the seam between the Control Plane (which decides what) and the Agent Mesh (which does the work). It makes agents interchangeable, executions observable, and artifacts traceable. This page describes how the mesh implements the canonical Agent Task Contract through the AgentTask and AgentExecution aggregates.

The contract is owned by two services: ConnectSoft.Factory.AgentMesh.AgentTaskService (the AgentTask aggregate) and ConnectSoft.Factory.AgentMesh.AgentExecutionService (the AgentExecution and SkillExecution aggregates).

AgentTask and AgentExecution

Aggregate Owns Purpose
AgentTask The unit of assigned work Carries intent, requested skill, context request, constraints, and lifecycle status.
AgentExecution A single attempt to fulfil a task Records the agent version, context package, skill/model/tool invocations, validation, and outcome.

A task may produce one AgentExecution per attempt; idempotent claiming guarantees a re-delivered Assigned task does not create duplicate executions.

Task Lifecycle

The lifecycle mirrors the canonical Agent Task Contract:

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 the Control Plane; awaiting claim. AgentTaskAssigned
ContextLoading Agent requests a context package. —
Executing Skill runs; model and tool invocations occur. AgentExecutionStarted, ModelInvoked, ToolInvoked
Validating Output checked by AgentValidationService. ValidationFailed (on failure)
Correcting AgentCorrectionService retries with feedback. CorrectionAttempted
Completed Validated artifacts registered. AgentTaskCompleted
Failed Escalated to human review or retried by workflow. AgentTaskFailed

Inputs (Task Assignment)

The mesh accepts the canonical assignment shape. Re-delivery with the same taskId is idempotent.

{
  "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"
}

Outputs (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"
}

Contract Rules

  1. Idempotent assignment — same taskId never spawns a duplicate AgentExecution.
  2. Context-grounded — execution must consume a context package; contextPackageId is recorded.
  3. Validated output — no artifact registers until validation passes against schema, naming, dependency, and policy rules.
  4. Bounded correction — maxCorrectionAttempts caps self-correction before human escalation.
  5. Full emission — every transition emits an event in the canonical envelope, so the lifecycle is replayable.