Core · Service · Active scaffold

platform-agent-service

Core service for asynchronous agent execution requests, persisting execution state, orchestrating MCP tool calls around AI generations and delivering callbacks to source products.

• TypeScript
• NestJS 11
• Prisma
• PostgreSQL
• BullMQ
• Redis
• AJV
• @platform/contracts-agent

Spec sheet

Boundary

Core / Agent execution

Runtime

NestJS 11 HTTP service plus BullMQ processor

Default port

3600

Proxy host

http://agent.cs.lvh.me:8080

Persistence

Dedicated agent-postgres via DATABASE_URL

Queue

BullMQ on Redis

Responsibilities

• Accept product-owned agent execution requests through an internal service-to-service API.
• Persist lifecycle state from QUEUED/RUNNING to terminal execution statuses.
• Dispatch model work through platform-mcp-service, optionally execute allowlisted MCP tools, and validate output against the requested schema.
• Send completion or failure callbacks to the originating product backend.

Interfaces and contract surface

• GET /health
• POST /internal/agent/executions
• GET /internal/agent/executions/:executionId

Consumers

• funnel backend
• cs-chat api

Dependencies and external touchpoints

• platform-mcp-service
• @platform/contracts-agent
• Agent Postgres
• Redis

Notes

• Tool-backed executions require an explicit toolPolicy allowlist from the consuming product.
• Terminal statuses include completed, skipped by policy/duplicate/model, failed and callback failed.

Source references

• platform-agent-service/package.json
• platform-agent-service/prisma/schema.prisma
• platform-agent-service/src/modules/agent-executions

Smoke test esecuzione

export AGENT_URL=http://127.0.0.1:3600
export INTERNAL_TOKEN=platform-local-stack-internal-token

curl -sS -X POST "$AGENT_URL/internal/agent/executions" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "tenantId": "demo",
    "sourceService": "manual",
    "sourceRef": "demo-run",
    "taskKey": "wiki-smoke",
    "provider": "template",
    "instructions": "Rispondi con JSON valido.",
    "input": {"message":"ping"},
    "outputSchema": {"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},
    "dispatch": false,
    "initialStatus": "SKIPPED_POLICY",
    "error": "manual smoke without dispatch"
  }'