Skip to main content

Invoke Agents & Tools

Invoke an Agent​

The examples below use APIM-style /ai paths because they are the routes a Replit or browser client normally calls in testing. The source-backed direct runtime paths omit that prefix, for example /sdac/agents/coordinator-release/generate.

Non-Streaming (Generate)​

POST /ai/\{domain\}/agents/\{slug\}/generate

Sends a prompt to an agent and waits for the complete response.

Example -- SDAC Coordinator Release:

curl -X POST "$BASE_URL/ai/sdac/agents/coordinator-release/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the fringe variance for this report?"
      }
    ]
  }'

Accepted input formats:

// Option 1: Messages array
{ "messages": [{ "role": "user", "content": "..." }] }

// Option 2: Shorthand prompt
{ "prompt": "Your question here" }

// Option 3: Alias
{ "message": "Your question here" }

Response:

{
  "text": "Fringe is 8.7% above threshold. Two new hires (Williams, Lee) account for $5,300.",
  "usage": {
    "promptTokens": 1200,
    "completionTokens": 85
  },
  "finishReason": "stop"
}

Streaming (SSE)​

POST /ai/\{domain\}/agents/\{slug\}/stream

Returns a Server-Sent Events stream with incremental response chunks.

SSE event types:

EventPayloadDescription
delta{ "content": "token" }Text chunk
tool-call{ "toolCallId": "...", "toolName": "..." }Tool invocation started
tool-result{ "toolCallId": "...", "success": true }Tool completed
usage{ "promptTokens": 100, "completionTokens": 50 }Token counts
done{ "success": true }Stream complete
error{ "message": "..." }Error occurred

Execute a Tool​

Tools have two source-backed route families:

  • generic Mastra execution: POST /api/tools/{toolId}/execute
  • domain-friendly execution: POST /{domain}/tools/{slug}

APIM can publish those as /ai/api/tools/{toolId}/execute and /ai/{domain}/tools/{slug}.

Domain Tool Route​

POST /ai/\{domain\}/tools/\{slug\}

Executes a tool with validated input. The request body is validated against the tool's Zod schema.

Example -- Validate SDAC Source Codes:

curl -X POST "$BASE_URL/ai/sdac/tools/validate-source-codes" \
  -H "Content-Type: application/json" \
  -d '{ "report_id": "Q1-2024-District123" }'

Response:

{
  "data": {
    "total_records_checked": 150,
    "error_count": 3,
    "warning_count": 2,
    "passed": false,
    "errors": [
      { "row": 15, "message": "Invalid source code '5' (must be 0-4)" }
    ]
  }
}

Example -- TAP Get Posts:

curl -X POST "$BASE_URL/ai/tap/tools/api-get-posts" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 10, "offset": 0 }'

Validation Errors​

If the input doesn't match the tool's schema, you get a 422 response:

{
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["report_id"],
        "message": "Required"
      }
    ]
  }
}

Start a Workflow​

POST /ai/\{domain\}/workflows/\{slug\}/start

Starts a workflow run with validated input.

Example -- TAP Tagging Suggestions:

curl -X POST "$BASE_URL/ai/tap/workflows/tagging-suggestions/start" \
  -H "Content-Type: application/json" \
  -d '{ "posts": [{ "postId": "12345", "tenantId": "tap", "university": { "id": "uol", "name": "University of Liverpool" }, "text": "Graduation day", "media": [{ "type": "image", "url": "https://example.com/post.jpg" }] }], "options": { "maxTagsPerPost": 5, "generateCaption": true } }'

Response:

{
  "runId": "44c34b7f-b5f8-4a0f-a44b-03d1fd260f17",
  "status": "running",
  "message": "Tagging suggestions workflow started",
  "progress": { "total": 1, "processed": 0, "succeeded": 0, "failed": 0, "skipped": 0 },
  "createdAt": "2026-06-23T12:00:00.000Z"
}

Workflow routes also expose create-run and runs/{runId} variants when the workflow supports run lifecycle operations.