Events¶

Target Architecture — Final-State Design

The Agent Mesh is fully event-driven. Every meaningful action — registration, assignment, execution, model and tool calls, validation, correction, completion, and health change — emits an event in the canonical envelope on Azure Service Bus via MassTransit. This is what makes the autonomous workforce observable, replayable, and traceable.

Events use NounVerbPastTense; commands use VerbNoun (see Naming Conventions).

Commands¶

Commands express intent and are handled by exactly one aggregate. They are internal to the mesh and not part of the public event stream.

Command	Handled by	Effect
`RegisterAgent`	`AgentDefinition`	Onboard an agent definition/version.
`RegisterSkill`	`SkillDefinition`	Onboard a skill definition/version.
`AssignAgentTask`	`AgentTask`	Place a task for execution.
`StartAgentExecution`	`AgentExecution`	Begin an execution attempt.
`InvokeModel`	`ModelInvocation`	Route and call a model provider.
`InvokeTool`	`ToolInvocation`	Call an MCP tool.
`ValidateOutput`	`ValidationResult`	Validate produced artifacts.
`RetryCorrection`	`CorrectionAttempt`	Re-run a skill with feedback.
`CompleteAgentExecution`	`AgentExecution`	Finalize with validated outputs.
`FailAgentExecution`	`AgentExecution`	Fail and escalate.

Domain Events¶

Emitted by aggregates after a state change, published within the Agent Mesh.

Event	Emitted by	Meaning
`AgentRegistered`	`AgentDefinition`	An agent version was registered.
`SkillRegistered`	`SkillDefinition`	A skill version was registered.
`AgentTaskAssigned`	`AgentTask`	A task was placed for execution.
`AgentExecutionStarted`	`AgentExecution`	An execution attempt began.
`ModelInvoked`	`ModelInvocation`	A model provider was called.
`ToolInvoked`	`ToolInvocation`	An MCP tool was called.
`ValidationFailed`	`ValidationResult`	Output failed validation.
`CorrectionAttempted`	`CorrectionAttempt`	A correction was attempted.
`AgentTaskCompleted`	`AgentTask`	Task finished with validated artifacts.
`AgentTaskFailed`	`AgentTask`	Task failed and escalated.
`AgentHealthChanged`	`AgentHealthStatus`	A pooled agent's health transitioned.

Integration Events¶

Domain events promoted to cross-platform contracts. These are versioned and consumed by other platforms (see Event Catalog).

Integration event	Primary consumers
`AgentTaskCompleted`	Control Plane (workflow advance), Knowledge (artifact ingest), Observability (quality attribution)
`AgentTaskFailed`	Control Plane (escalation), Observability (failure analysis)
`AgentRegistered` / `SkillRegistered`	Control Plane, Marketplace (agent/skill packs), Knowledge
`ModelInvoked` / `ToolInvoked`	Observability (cost & usage), Governance (policy audit)
`AgentHealthChanged`	Control Plane (scheduling), Observability (capacity)

Canonical Envelope¶

All events use the canonical envelope. Example for AgentTaskCompleted:

{
  "eventId": "evt-7b3c1f9a-2e44-4c1a-9b6d-0f2a8c3d5e10",
  "eventType": "AgentTaskCompleted",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40",
  "causationId": "evt-execution-started-id",
  "occurredAt": "2026-06-11T00:04:30Z",
  "payload": {
    "taskId": "task-4d21",
    "executionId": "exec-8841",
    "agentId": "ConnectSoft.Agent.SolutionArchitect",
    "agentVersion": "3.2.0",
    "skillId": "ConnectSoft.Skill.DesignServiceBlueprint",
    "outputArtifacts": ["art-serviceblueprint-reservations-1"],
    "validationResultId": "val-22",
    "tokensUsed": 14210
  }
}

Topics¶

Events are published to Azure Service Bus topics; selected envelope fields are mirrored to application properties (cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id) so subscriptions filter without deserializing the body.

Topic	Carries
`agent-mesh.registry`	`AgentRegistered`, `SkillRegistered`
`agent-mesh.tasks`	`AgentTaskAssigned`, `AgentTaskCompleted`, `AgentTaskFailed`
`agent-mesh.executions`	`AgentExecutionStarted`, `ModelInvoked`, `ToolInvoked`, `ValidationFailed`, `CorrectionAttempted`
`agent-mesh.health`	`AgentHealthChanged`

Event-Flow Diagram¶

flowchart TB
    Assign["AgentTaskAssigned"] --> Start["AgentExecutionStarted"]
    Start --> Model["ModelInvoked"]
    Start --> Tool["ToolInvoked"]
    Model --> Validate{"Validation"}
    Tool --> Validate
    Validate -->|"failed"| VFail["ValidationFailed"]
    VFail --> Corr["CorrectionAttempted"]
    Corr --> Validate
    Validate -->|"passed"| Complete["AgentTaskCompleted"]
    Corr -->|"budget exhausted"| Fail["AgentTaskFailed"]
    Complete --> KG["Knowledge Platform"]
    Complete --> Obs["Observability & Feedback"]
    Fail --> CP["Control Plane"]

Hold "Alt" / "Option" to enable pan & zoom

Consumer Rules¶

Idempotency — deduplicate on eventId; workers add a handler-scoped idempotency key.
Tenant guard — assert tenantId before any store access.
Trace propagation — traceId/correlationId flow into OpenTelemetry spans and logs.
Poison handling — unprocessable messages dead-letter with the full envelope preserved.