AI Agents

SureCentric supports autonomous AI Agents that can execute platform tasks — schema compilations, data queries, MCP tool calls, sandbox code execution, and dashboard provisioning — with full audit trail attribution and human oversight controls.

Agent Types

Agent	Primary Role	Key MCP Tools
SureAgent	Schema lifecycle orchestration — compile, deploy, branch, rollback	dolt_commit, dolt_branch, dolt_merge, schema_compile, schema_deploy
DataAgent	Clinical analytics — NL2SQL, DuckDB queries, dataset provisioning	duckdb_query, superset_provision, nl2sql
SchemaAgent	Schema authoring assistance — suggest JSON-LD structures from clinical standards	schema_suggest, owl_validate, sparql_query

Agent Identity — The "Workflow UUID" Pattern

AI Agents in SureCentric are identified using the same pattern the SureClinical platform (network-service) applies to Nuxeo workflow processes: each agent execution gets a UUID and emits a AGENT_RUN_START / AGENT_RUN_FINISH event pair.

This creates a traceable execution envelope around every action the agent takes — analogous to how SC's shouldLogWorkflowProcessStart captures a workflow's process UUID at the start of every Nuxeo workflow.

agent_run_id: uuid-abc
  │
  ├── AGENT_RUN_START     spawned_by: [email protected]  task: "Deploy edc.v1.1"
  │
  ├── AGENT_TOOL_CALL     tool: dolt_branch  args: {name: "schema/edc-v1.1-agent-abc"}
  ├── AGENT_TOOL_CALL     tool: schema_compile  args: {schemaId: "edc-v1.1"}
  ├── AGENT_ACTION        event_type: SCHEMA_DEPLOY  resource_id: edc-v1.1
  ├── AGENT_TOOL_CALL     tool: superset_provision  args: {profileId: "prof-001"}
  │
  └── AGENT_RUN_FINISH    outcome: success  duration_ms: 4231  tokens_used: 1840

Agent Registry

Every agent run is recorded in the agent_registry table:

Field	Description
agent_run_id	UUID v4 — unique per run, used as actor_id in audit trail
agent_name	SureAgent, DataAgent, SchemaAgent
agent_version	Semver
agent_model	LLM powering the agent: claude-3-5-sonnet, gpt-4o, etc.
task	Human-readable description of the assigned task
mcp_tools	JSON array of tool names available to this agent
sandbox_enabled	Boolean — whether the agent can execute sandbox code
spawned_by	actor_id of the human or system that invoked this agent
parent_run_id	Set when this agent is spawned by another agent (nested agents)
started_at / finished_at	Execution timestamps
tokens_used	LLM token consumption for cost tracking

Dolt Branch Naming for Agents

Agent-initiated schema branches are named with the agent_run_id suffix to distinguish them from human-authored branches in dolt_branches and dolt_log:

schema/edc-v1.1-agent-uuid-abc

Human review is required before merging any agent-initiated branch to main.

Nested Agents

An orchestrator agent can spawn sub-agents. The parent-child relationship is recorded via parent_run_id:

agent_run_id: aaa-supervisor    spawned_by: user:[email protected]
  └─ agent_run_id: bbb-sub     spawned_by: agent:aaa-supervisor
                                parent_run_id: aaa-supervisor

This allows a full chain-of-custody query:

WITH RECURSIVE agent_chain AS (
  SELECT agent_run_id, agent_name, spawned_by, parent_run_id, 0 AS depth
  FROM agent_registry WHERE agent_run_id = 'aaa-supervisor'
  UNION ALL
  SELECT r.agent_run_id, r.agent_name, r.spawned_by, r.parent_run_id, c.depth + 1
  FROM agent_registry r JOIN agent_chain c ON r.parent_run_id = c.agent_run_id
)
SELECT * FROM agent_chain ORDER BY depth;

Sandbox Execution

Agents with sandbox_enabled: true can write and execute code in an isolated container. All sandbox executions produce an AGENT_SANDBOX_EXEC audit event recording:

• Language and runtime
• Code submitted (truncated to 2 KB in the audit record)
• Stdout/stderr output
• Exit code and duration

REST API

Endpoint	Description
POST /api/agents/runs	Register a new agent run, receive agent_run_id
PATCH /api/agents/runs/:runId/finish	Mark a run complete with outcome and tokens
GET /api/agents/runs	List all agent runs (filterable by agent name, outcome, date)
GET /api/agents/runs/:runId	Full run details + all associated audit events