Trasversale · Package · Active seed

@platform/contracts-agent

Shared type contract for asynchronous agent execution requests, MCP tool policy, tool trace, lifecycle statuses, usage data, callbacks and detail responses.

• TypeScript declarations
• Dual package exports

Spec sheet

Package name

@platform/contracts-agent

Repository path

platform-shared-packages/packages/contracts-agent

Exports

CommonJS and ESM entrypoints plus type declarations

Responsibilities

• Define the AgentExecutionStatus union used by platform-agent-service and product consumers.
• Define request, create response, detail response, callback payload and token usage shapes.
• Define toolPolicy and toolTrace shapes for products that need real MCP execution.
• Keep callback contracts stable between Core agent runtime and product BFFs.

Interfaces and contract surface

• Package root export

Consumers

• platform-agent-service
• funnel backend
• cs-chat api

Notes

• The runtime contract includes terminal statuses for policy skips, duplicate skips, model skips, failures and callback failures.

Source references

• platform-shared-packages/packages/contracts-agent/package.json
• platform-shared-packages/packages/contracts-agent/index.d.ts

Surface condivisa

@platform/contracts-agent descrive il contratto TypeScript product-agnostic per creare execution asincrone, ricevere callback e leggere stato runtime da platform-agent-service.

Tipi principali:

• AgentExecutionCreateRequest e AgentExecutionCreateResponse
• AgentExecutionDetailResponse
• AgentExecutionCallbackPayload
• AgentExecutionUsage
• AgentToolPolicy
• AgentToolTraceItem
• AgentExecutionStepResponse e AgentExecutionStepsResponse
• AgentRunCreateRequest e AgentRunCreateResponse
• AgentRunDetailResponse
• AgentRunNodeResponse e AgentRunNodesResponse
• AgentRunCallbackPayload
• AgentRunStrategy

AgentToolPolicy supporta mode, allowedTools, maxSteps e i limiti runtime opzionali maxToolCalls, toolTimeoutMs, maxRepeatedToolCalls e maxTotalTokens. Il servizio agent filtra comunque platform_ai_generate_text dai tool invocabili dal modello.

Gli step persistenti usano AgentExecutionStepType con valori MODEL_ACTION, TOOL_CALL, FINAL_OUTPUT, ERROR e AgentExecutionStepStatus con valori STARTED, SUCCEEDED, FAILED. toolTrace rimane nel payload callback per compatibilita, ma e derivato dagli step TOOL_CALL del runtime.

Le run multi-agent usano AgentRunStrategy con valori parallel e sequential. parallel richiede un aggregator; sequential esegue gli agenti nell'ordine dichiarato. I node espongono ruolo SPECIALIST o AGGREGATOR e stati PENDING, QUEUED, RUNNING, COMPLETED, FAILED e SKIPPED_DEPENDENCY.