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
• InlineAgentExecutionRequest e ProfileAgentExecutionRequest, mutuamente esclusivi
• AgentExecutionDetailResponse
• AgentExecutionCallbackPayload
• AgentExecutionAttempt, AgentExecutionCallbackDelivery e AgentExecutionRetention
• AgentExecutionRetryRequest e le response di retry callback/redazione
• 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.

Le execution singole basate su profileKey vietano override inline di provider, modello, istruzioni, schema e tool policy. Richiedono callback e retention REDACT_AFTER_CALLBACK; il dettaglio espone lo snapshot tramite chiave/versione/hash, la catena attempt, resultStatus separato dallo stato delivery e lo stato di redazione. status resta nel contratto per compatibilita con i consumer esistenti, ma un errore di callback non cambia piu l'esito del modello. ProfileAgentExecutionRequest.idempotencyKey e opzionale, valida soltanto per request profile-based e scoped dal servizio su tenant e source service. Il replay con la stessa request restituisce la execution esistente; riusare la chiave con un payload differente produce 409. dispatch non partecipa all'hash della request. AgentExecutionRetryRequest richiede un nuovo input e accetta dispatch:false per creare l'attempt QUEUED senza accodarlo: il consumer salva prima il nuovo executionId e poi usa resume, senza poter modificare snapshot o correlazione.

I metadata fanno parte dell'hash canonico del profilo: modificarli via PUT crea una nuova versione immutabile. Il PATCH di una versione puo cambiare soltanto lo stato ACTIVE/INACTIVE.