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.

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.

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. 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:

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.

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
• Platform Engineer Agent
• MCP guardrails configuration schema
• AI, agents, and MCP introduction