# Operaciones a cargo del proveedor

Invoca operaciones de agentes y herramientas registradas sin importar su implementación.

Source: https://goa.design/es/docs/2-goa-ai/provider-operations/

Relative links resolve against the source URL above.


Invoca operaciones de agentes y herramientas registradas sin importar su implementación.

## Iniciar una operación

El host autoriza al llamador y envía la declaración generada y los argumentos
originales. `StartOperation` usa una sesión existente del host; `StartOneShotOperation`
no crea una sesión. El worker del proveedor valida su exportación y prepara la
configuración inmutable seleccionada. El consumidor no necesita la definición privada
del agente ni `WithAgentExecutors`.

```go
handle, err := rt.StartOneShotOperation(
    ctx, runID, operation, arguments, labels, nil,
)
if err != nil {
    return err
}
output, err := handle.Wait(ctx)
if err != nil {
    return err
}
```

Usa `StartToolOperation` o `StartOneShotToolOperation` con la selección exacta
conservada del Registry y su `RegisteredInvocation`. Configura la misma fuente Registry
y el cliente generado. Los agentes nativos usan el workflow y la cola declarados. Los
servicios usan `WithToolWorkflowQueue` y un worker que llama a `RegisterToolWorkflow`;
no necesitan agente, planificador, modelo ni conversación. Un registro o una etiqueta no
concede acceso.

## Seleccionar el historial explícitamente

Registra `AgentToolResolver` en el worker del proveedor antes de sellar el runtime o
enviar trabajo. Su firma es `func(context.Context, genregistry.ExecutionInvocation,
string, *runtime.ToolCall) (*runtime.AgentToolConfiguration, error)`. Recibe la
invocación original, la referencia inmutable y la llamada validada. Devuelve `History`
obligatorio, etiquetas, política y, opcionalmente, metadatos y referencias de prompts.

```go
configuration := &runtime.AgentToolConfiguration{
    History: runtime.LiteralAgentHistory(messages),
    Labels: labels,
    Policy: policy,
}
```

Para otro turno, usa `runtime.NextTurnAgentHistory(completedRunID, systemMessages,
freshMessages)`. La fuente debe ser una ejecución completada correctamente del mismo
agente y sesión. Los mensajes nuevos no pueden contener mensajes de sistema.
`WithoutPriorReasoning()` excluye razonamiento del historial recibido y heredado; la
exclusión persiste en turnos posteriores. Las operaciones sin sesión no heredan otra
sesión. La repetición exacta reutiliza la preparación aceptada.

## Resultados, entrada y cancelación

El motor se hace cargo del trabajo aceptado antes de la preparación. Repetir la
solicitud exacta observa la ejecución original; modificarla provoca un conflicto. Un
fallo o una cancelación anterior al primer registro del runtime conserva un resultado
terminal en el motor. Observa el trabajo aceptado antes de concluir que la ausencia de
un registro significa que no comenzó.

Las entradas, salidas, registros e instantáneas comunes requieren `Subject` generado: el
identificador real del agente, o la fuente Registry y el nombre cualificado de la
herramienta de servicio. Un servicio no tiene un agente ficticio ni una sesión oculta.
Los clientes de agentes y su historial siguen requiriendo identidad de agente.

`planner.PlanInput.ParentTool` y `planner.PlanResumeInput.ParentTool` contienen el
contrato de resultado seleccionado para delegación y operaciones directas. El
planificador devuelve `planner.FinalToolResult` conforme al contrato; solo texto de
conversación se rechaza. Usa `FinalToolResult` para el resultado tipado y `Final` para
texto. Lee eventos paginados solo para consultar el historial de diagnóstico.

La continuación restaura la operación original y admite un solo sucesor. Para servicios,
el host guarda de forma duradera el predecesor, el nuevo ID y la respuesta tipada; su
worker llama a `StartToolContinuation` y `EnsureToolContinuationCompletion`. La
cancelación del padre sigue las relaciones aceptadas y conserva la limpieza pendiente.
La finalización no depende de que el cliente vuelva a intentarlo.

## Contratos de entrada generados

Dentro de `Use` de un toolset compilado, `BindInput("read", "scope")` elimina un campo
obligatorio de nivel superior de la entrada visible al modelo de ese consumidor. Instala
el helper tipado generado en cada actividad de planificación para aportar el valor de la
aplicación. El proveedor recibe la entrada original completa. Se rechazan campos
opcionales, inyectados, desconocidos, repetidos o rutas anidadas; un contrato remoto
Registry requiere una declaración compilada.

Los codecs admiten `Any` o `Bytes` representados explícitamente como `json.RawMessage`,
conservando JSON y números exactos. Un mapa declarado con `Meta("struct:tag:json",
",embed")` acepta miembros adicionales según el contrato de sus valores. Se rechazan
claves duplicadas, colisiones y valores inválidos. Los objetos normales siguen cerrados
y los bytes normales usan base64.

## Actualización y reversión {#upgrade}

Es una actualización coordinada de código, formatos de intercambio y datos guardados.
Regenera y recompila proveedores y consumidores; sustituye `Messages` del resolver por
`History` obligatorio y registra el resolver en el proveedor. El historial vacío
explícito es `runtime.LiteralAgentHistory(nil)`; se rechaza un `AgentHistory` sin
seleccionar. Los destinos nativos requieren `Executor`, `Configuration`, `Workflow` y
`Queue`. Valida todos los grupos guardados, incluidos los retirados.

Las suspensiones actuales usan `goa-ai.run-suspension.v14` y los resultados superiores
`json/goa-ai-run-output-v3`. Se rechazan formatos anteriores. Actualiza Stores,
adaptadores del motor, registros, consumidores y transportes para `Subject` obligatorio.
Inventaría inicios, preparaciones, selecciones, checkpoints, historiales padres con
resultados hijos, exportaciones y copias de resultados. Termina el trabajo con sus
workers anteriores o realiza una conversión del propietario verificada mediante replay.
No compartas una cola entre preparaciones antiguas y nuevas mientras quede trabajo
antiguo.

Coordina lectores y escritores desplegados por separado. La reversión requiere datos,
declaraciones, solicitudes y workers compatibles; revertir solo el binario tras nuevas
escrituras no es seguro. El framework no infiere ejecutores ni ofrece un modo de
compatibilidad permanente.

Contratos detallados del framework:

- [Run subjects](https://github.com/goadesign/goa-ai/blob/main/docs/run-subjects.md)
- [Workflow results](https://github.com/goadesign/goa-ai/blob/main/docs/workflow-results.md)
- [Native declarations](https://github.com/goadesign/goa-ai/blob/main/docs/native-agent-declarations.md)
- [JSON codecs](https://github.com/goadesign/goa-ai/blob/main/docs/json_codecs.md)