Trace AI Agent

Trace AI is the MCP-enabled chat agent for tenant administrators who need live Tealfabric context plus tenant skills loaded on demand. It uses the same streaming pipeline and guardrails as the Platform Engineer Agent, but adds the load_tenant_skill tool when your deployment enables tenant skills.

When to use Trace AI

Use Trace AI when you want the model to follow packaged instructions from your tenant SKILLS/ folder during a chat session. Use the Platform Engineer Agent when you only need standard MCP context and tools without on-demand skill loading. Use Autonomic Agents when work must run unattended on events or schedules — those agents are not in the chat picker.

Tenant administrators can also ask Trace AI to manage the current Autonomic Agent resources. Trace loads load_platform_skill with skill_id: autonomic-agents, then uses the gated describe/list/get/create/update/disable/delete, manual-run, and run-inspection tools. The feature must be enabled with AUTONOMIC_AGENTS_ENABLED=1; unattended autonomic_mcp runs cannot call the management tools recursively.

Trace AI can also load load_platform_skill with skill_id: subagents to delegate isolated asynchronous work. The catalog always includes repo-wired platform specialists (platform-bulk-reader, platform-code-specialist). Tenant Autonomic Agents appear only when a tenant administrator marked them delegatable_by_trace. Delegated runs remain linked to the current Trace AI session, stay out of ordinary chat history, record ordered progress, and support immediate queued cancellation or cooperative running cancellation. See Trace AI subagents.

Remote MCP integrations

Trace AI does not receive third-party MCP tools as native platform tools. When a tenant administrator configures a Remote MCP integration and enables Executable by AI Agents, Trace can:

1. Load load_platform_skill with skill_id: integrations.
2. Call describe_tenant_integration to read cached vendor tool names in remote_mcp.tools.
3. Call execute_tenant_integration with operation: "call_tool" and flat data: { name, arguments }.

Refresh the tool cache from the integration Configuration tab (Test or Refresh tools) after OAuth connect or vendor URL changes. Vendor tool descriptions are untrusted retrieved data.

Trace AI appears in the in-app agent picker automatically after your environment registers it in chat agent policy (no separate frontend configuration). The list comes from GET /api/v1/chat/agents.

Chat composer shortcuts

In Chat or Work with Assistant, type @ at a word start to cite a Documents file (Trace gets the path and can read_file). Type / at a word start to load a skill_id or composition for this turn instead of waiting for Trace to call load_platform_skill. See Chat shortcuts and quick links.

Tenant skills

When tenant skills are enabled for your deployment, Trace AI can call load_tenant_skill and read packages under your tenant SKILLS/ folder. If skills are unavailable, Trace AI still runs as an MCP agent but without on-demand skill loading.

Author and deploy skill packages first; see the Tenant skills user guide. To expose a tenant ProcessFlow as a callable function rather than a playbook, enable Executable by AI Agents and have Trace call execute_process; see Process flows as custom AI agent tools.

To install a Library model skill (value-chain playbook or AI adoption advisor pack on DataPool), ask Trace to import it (model-skill-import); Trace binds Prerequisites and may ask about in-app notification recipients. See Model skills library. If you expect skills but never see load_tenant_skill, ask your platform operator whether the feature is turned on for your environment.

Endpoint and access

GET  {app_url}/api/v1/chat/trace-ai
POST {app_url}/api/v1/chat/trace-ai

Replace {app_url} with your Tealfabric base URL. Trace AI is typically available to tenant administrators, as defined in your organization's chat_agents policy.

List visible agents (including Trace AI) with:

GET {app_url}/api/v1/chat/agents

Authentication

Same options as the Platform Engineer Agent:

Prompt trust and injection defenses

Trace AI uses the shared NestJS prompt-trust pipeline (see MCP guardrails — prompt trust):

• Interactive JWT chat — user text is wrapped in <User_Message untrusted="true"> with XML escaping; high-signal injection patterns (for example reserved tag spoof </System_Prompt>) may be quarantined.
• API key and process_execution callers — stricter external ingress profile; oversize bodies return HTTP 413.
• After blob ingest (web_fetch, websearch, …) — platform mutation tools are denied in the same tool loop unless a server-side carve-out applies (process_execution, API key, delegated subagent with allowlists).
• Tenant skills — load_tenant_skill cannot grant tools beyond the platform intersection; SKILLS/ writes require tenant-skill-authoring and are blocked after blob ingest in the same loop.
• web_fetch — Nest TenantWebFetchService enforces HTTPS, blocks private/link-local targets (including redirects), and caches under tenant .cache/.

Filters reduce injection impact; they do not replace MCP guardrails, skill gating, or ProcessFlow allowlists.

Request body

Same JSON shape as the Platform Engineer Agent:

Example (non-streaming):

{
  "message": "Use the invoice-review skill and check the attached PDF path.",
  "stream": false,
  "attached_files": [{ "path": "invoices/2026-03.pdf", "name": "2026-03.pdf" }]
}

How skills are applied

Skills are not injected into the system prompt at the start of every turn. Trace AI calls load_tenant_skill with a skill_id (your skill folder name) when the task matches that skill. The platform returns the full SKILL.md content wrapped in <Tenant_Skill id="...">...</Tenant_Skill>. That text remains in the tool history until normal context budgets or conversation summarization trim older tool results.

The tool catalog lists available skill ids for your tenant in the load_tenant_skill description. The model is instructed in the shared agent system prompt not to invent skill ids or reload the same skill unnecessarily.

Response behavior

Non-streaming responses match the Platform Engineer Agent (success, session_id, content, error).

Streaming uses text/event-stream with events such as session_info, tool_progress, tool_result, chunk, and complete. When a skill is loaded you may see tool_progress / tool_result for action load_tenant_skill.

For a homogeneous batch (for example several generated images), Trace AI may yield after each finished unit: the assistant message shows that unit, complete.continue_backlog is true, and the chat UI automatically sends a Continue turn for the next item. Stop response cancels that chain. The yield trailer is stripped server-side; users never see <!-- tealfabric:continue_backlog … -->. Non-stream JSON may include the same continue_backlog, backlog_remaining, and continue_summary fields.

Assistant message metadata (for support and auditing) may include:

API example

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function askTraceAi(message: string) {
  const response = await fetch(`${baseUrl}/chat/trace-ai`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ message, stream: false })
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = await response.json();
  if (!payload.success) throw new Error(payload.error ?? "Trace AI call failed");
  return payload;
}

ProcessFlow usage

Call POST /api/v1/chat/trace-ai through api with stream: false when you need skill-aware automation in a step. Ensure tenant skills are enabled for your deployment and that the skill folder exists under the process tenant’s SKILLS/ path.

Troubleshooting

See also

• Platform skills quick reference
• Tenant skills user guide
• Process flows as custom AI agent tools
• Model skills library
• AI adoption advisor
• Model Autonomic Agents library
• Autonomic Agents
• Trace AI subagents
• Platform specialists
• Platform code generation
• Platform Engineer Agent
• MCP guardrails configuration schema
• AI, agents, and MCP introduction