Referencia de comandos A2A

Esta página documenta todos los comandos de iac-code relacionados con A2A. Úsala cuando necesites nombres exactos de opciones, patrones comunes de comandos y el significado operativo de cada flag.

Resumen de comandos

Comando	Propósito
`iac-code a2a`	Ejecutar iac-code como servidor A2A
`iac-code a2a-client call`	Descubrir una Agent Card remota y enviar un prompt
`iac-code a2a-client discover`	Obtener y opcionalmente verificar una Agent Card
`iac-code a2a-client task-get`	Obtener una tarea por ID
`iac-code a2a-client task-list`	Listar tareas con filtros y paginación
`iac-code a2a-client task-cancel`	Cancelar una tarea activa
`iac-code a2a-client task-subscribe`	Suscribirse a un stream de eventos de una tarea activa
`iac-code a2a-client push-config-create`	Crear una configuración de notificación push de tarea
`iac-code a2a-client push-config-get`	Obtener una configuración de notificación push de tarea
`iac-code a2a-client push-config-list`	Listar configuraciones de notificación push de tarea
`iac-code a2a-client push-config-delete`	Eliminar una configuración de notificación push de tarea
`iac-code a2a-client extended-card`	Obtener la Agent Card extendida autenticada
`iac-code a2a-route-preview`	Previsualizar la selección local de ruta para `a2a-client call`

Todos los comandos de cliente HTTP aceptan las mismas opciones de autenticación:

Opción	Descripción
`--token`	Token Bearer enviado como `Authorization: Bearer <token>`
`--basic-username`	Nombre de usuario de Basic auth
`--basic-password`	Contraseña de Basic auth
`--api-key`	Valor de clave de API
`--api-key-header`	Nombre del encabezado de clave de API; por defecto es `X-API-Key`

Configuración del cliente A2A

Todos los subcomandos a2a-client aceptan un archivo de configuración YAML a nivel de grupo:

iac-code a2a-client --config a2a-client.yml call --prompt "Create a VPC"

Las opciones de CLI sobrescriben los valores de configuración. Usa la configuración para conexión estable, autenticación, verificación, enrutamiento y ajustes repetidos de tareas o push; mantén el texto de prompts puntuales en la línea de comandos.

url: http://127.0.0.1:41242/
token: your-bearer-token
basic-username: iac-code
basic-password: your-password
api-key: your-api-key
api-key-header: X-IAC-Code-Key
verify-card-secret: your-card-signing-secret
verify-card-jwks-url: https://a2a.example.com/.well-known/jwks.json
require-card-signature: true
timeout: 30
cwd: /path/to/workspace
context-id: ctx-123
task-id: task-123
config-id: webhook-1
callback-url: https://hooks.example.com/a2a
notification-token: notification-token
auth-scheme: bearer
auth-credentials: callback-token
routes:
  - name: ros
    url: http://127.0.0.1:41242/
    skills:
      - iac_generation
    tags:
      - ros
      - template

`iac-code a2a`

Ejecuta iac-code como servidor A2A.

iac-code a2a

De forma predeterminada, el servidor se enlaza a 127.0.0.1:41242 y sirve JSON-RPC sobre HTTP. El puerto 41242 es el predeterminado de iac-code; no es un puerto A2A registrado.

Opciones básicas del servidor

Opción	Predeterminado	Descripción
`--config`	vacío	Archivo de configuración YAML que contiene opciones del servidor A2A
`--host`	`127.0.0.1`	Host del servidor HTTP
`--port`	`41242`	Puerto del servidor HTTP
`--transport`	`http`	Transporte del servidor: `http`, `stdio`, `unix`, `websocket`, `grpc`, `grpc-jsonrpc` o `redis-streams`
`--thinking-exposure`	`tool-trace`	Expone un tipo de señal de thinking A2A; repite para varios. Valores: `raw-thinking`, `tool-trace`
`--debug`, `-d`	`false`	Habilitar logging de depuración

Ejemplo:

iac-code a2a --host 127.0.0.1 --port 41242 --debug

Configuración YAML

Usa --config para autenticación, almacenamiento, firma, ajustes específicos de transporte, entrega push y otros detalles de despliegue. Las claves pueden usar guiones o guiones bajos. Los flags comunes de CLI --host, --port y --transport sobrescriben los valores del archivo de configuración.

host: 127.0.0.1
port: 41242
transport: http
token: local-dev-token
persistence-dir: .iac-code-a2a/state
artifact-dir: .iac-code-a2a/artifacts
push-notifications: true

Ejecútalo con:

iac-code a2a --config a2a-server.yml --port 41243

Autenticación HTTP

La autenticación es opcional. Configura la autenticación del servidor en YAML o con variables de entorno. Si no se configura ningún ajuste de autenticación, las solicitudes no están autenticadas. Cuando se configuran uno o más esquemas, una solicitud puede satisfacer cualquier esquema configurado.

Clave de configuración	Variable de entorno	Descripción
`token`	`IACCODE_A2A_HTTP_TOKEN`	Token Bearer
`basic-username`	`IACCODE_A2A_BASIC_USERNAME`	Nombre de usuario de Basic auth
`basic-password`	`IACCODE_A2A_BASIC_PASSWORD`	Contraseña de Basic auth
`api-key`	`IACCODE_A2A_API_KEY`	Valor de clave de API
`api-key-header`	`IACCODE_A2A_API_KEY_HEADER`	Nombre del encabezado de clave de API

Token Bearer:

token: local-dev-token

Basic auth:

basic-username: iac-code
basic-password: local-dev-password

Clave de API:

api-key: local-dev-key
api-key-header: X-IAC-Code-Key

Persistencia y artefactos

Clave de configuración	Predeterminado	Descripción
`persistence-dir`	`~/.iac-code/a2a`	Metadatos JSON locales para tareas, contextos, rutas y configuraciones push
`artifact-dir`	`<persistence-dir>/artifacts`	Almacén local de payloads de artefactos

La persistencia refleja instantáneas de tareas y contextos como metadatos de restauración. No reinicia una tarea asyncio en curso después de un fallo del proceso.

persistence-dir: ~/.iac-code/a2a
artifact-dir: ~/.iac-code/a2a/artifacts

Firma de Agent Card

Clave de configuración	Descripción
`signing-secret`	Secreto HMAC usado para firmar la Agent Card pública

El servidor emite campos JWS AgentCardSignature del SDK de A2A. El modo simétrico usa HS256.

signing-secret: local-card-signing-secret

Entrega de notificaciones push

Clave de configuración	Predeterminado	Descripción
`push-notifications`	`false`	Habilitar métodos de configuración de notificaciones push de tareas A2A y entrega de estados terminales
`push-queue`	`local-file`	Backend de cola push: `local-file` o `redis-streams`
`push-redis-url`	vacío	URL de Redis para la cola push respaldada por Redis
`push-stream`	`iac-code:a2a:push`	Stream de Redis para trabajos push
`push-retry-key`	`iac-code:a2a:push:retry`	Conjunto ordenado de Redis para reintentos retrasados
`push-dead-stream`	`iac-code:a2a:push:dead`	Stream de Redis para trabajos de dead-letter
`push-consumer-group`	`iac-code-push`	Grupo de consumidores Redis para workers push
`push-consumer-name`	vacío	Nombre de consumidor Redis para este worker
`push-lease-timeout-ms`	`300000`	Timeout de lease pendiente de Redis

Cola de archivo local:

push-notifications: true
persistence-dir: ~/.iac-code/a2a
push-queue: local-file

Cola Redis Streams:

push-notifications: true
push-queue: redis-streams
push-redis-url: redis://localhost:6379/0
push-stream: iac-code:a2a:push
push-retry-key: iac-code:a2a:push:retry
push-dead-stream: iac-code:a2a:push:dead
push-consumer-group: iac-code-push
push-consumer-name: worker-1

La entrega push respaldada por Redis requiere el extra a2a-redis.

Opciones de transporte

Transporte	Comando	Notas
HTTP JSON-RPC y REST	`iac-code a2a --transport http`	Predeterminado. Anuncia interfaces `JSONRPC` y `HTTP+JSON`.
stdio	`iac-code a2a --transport stdio`	Frames JSON-RPC personalizados experimentales sobre entrada/salida estándar.
Socket Unix	`iac-code a2a --config a2a-server.yml --transport unix`	Requiere `socket-path` en la configuración.
WebSocket	`iac-code a2a --config a2a-server.yml --transport websocket`	Usa `ws-path` desde la configuración, con valor predeterminado `/a2a`.
gRPC	`iac-code a2a --config a2a-server.yml --transport grpc`	Usa `grpc-host` y `grpc-port` desde la configuración.
gRPC JSON-RPC	`iac-code a2a --config a2a-server.yml --transport grpc-jsonrpc`	Envoltorio JSON-RPC personalizado sobre gRPC.
Redis Streams	`iac-code a2a --config a2a-server.yml --transport redis-streams`	Requiere `redis-url` en la configuración.

Opciones de transporte Redis Streams:

Clave de configuración	Predeterminado	Descripción
`redis-url`	vacío	URL de conexión Redis; requerida para `--transport redis-streams`
`request-stream`	`iac-code:a2a:requests`	Nombre del stream de solicitudes
`response-stream`	`iac-code:a2a:responses`	Nombre del stream de respuestas
`consumer-group`	`iac-code`	Grupo de consumidores del stream de solicitudes

Exposición de thinking

Clave de configuración	Predeterminado	Descripción
`thinking-exposure`	`tool-trace`	Tipos de señales de runtime que no son respuesta expuestas mediante A2A `metadata.iac_code`. Usa una lista YAML, una cadena separada por comas o flags `--thinking-exposure` repetidas. Los valores admitidos son `tool-trace` y `raw-thinking`.

tool-trace conserva los metadatos existentes de progreso de herramientas, permisos y resultados. raw-thinking emite chunks de razonamiento del provider como actualizaciones metadata.iac_code.thinking con type: raw_thinking y text. iac-code no produce actualmente eventos separados de thought-summary o progress-summary, por lo que no son tipos de exposición válidos.

thinking-exposure:
  - tool-trace
  - raw-thinking

Comportamiento de permisos

Clave de configuración	Predeterminado	Descripción
`auto-approve-permissions`	`false`	Aprobar automáticamente solicitudes de permisos de herramientas generadas durante turnos A2A

Sin auto-approve-permissions: true, el modo A2A rechaza solicitudes de permisos y emite metadatos de permisos. Úsalo solo para entornos de automatización de confianza.

`iac-code a2a-client call`

Descubre una Agent Card, elige el endpoint anunciado y envía un prompt.

iac-code a2a-client --config a2a-client.yml call \
  --prompt "Create a ROS VPC template with two vSwitches." \
  --cwd "$PWD"

Opción	Predeterminado	Descripción
`--url`	vacío	URL base del agente A2A o URL del endpoint JSON-RPC; puede venir de la configuración
`--route`	repetible	Especificación de ruta usada cuando `--url` se omite
`--route-name`	vacío	Ruta con nombre que seleccionar
`--prompt`, `-p`	requerido	Texto del prompt
`--cwd`	`.`	Ruta de espacio de trabajo enviada como `message.metadata.iac_code.cwd`
`--context-id`	vacío	ID de contexto A2A existente para un mensaje de seguimiento
`--verify-card-secret`, `--signing-secret`	vacío	Secreto HMAC para verificación de Agent Card
`--verify-card-jwks-url`	vacío	URL JWKS remota usada para verificación de Agent Card
`--require-card-signature`, `--require-signature`	`false`	Rechazar Agent Cards sin firmar o inválidas
`--timeout`	`30.0`	Timeout de llamada en segundos
`--stream`	`false`	Usar `SendStreamingMessage` e imprimir eventos de stream

Seguimiento en el mismo contexto:

iac-code a2a-client --config a2a-client.yml call \
  --context-id ctx-123 \
  --prompt "Now add outputs for the VPC and vSwitch IDs." \
  --cwd "$PWD"

Streaming:

iac-code a2a-client --config a2a-client.yml call \
  --prompt "Review this Terraform module." \
  --cwd "$PWD" \
  --stream

Requerir una Agent Card firmada:

iac-code a2a-client --config a2a-client.yml call \
  --prompt "Generate a production VPC template." \
  --cwd "$PWD"

Verificar usando una URL JWKS remota:

iac-code a2a-client --config jwks-client.yml call \
  --prompt "Review the ROS stack."

`iac-code a2a-client discover`

Obtiene e imprime una Agent Card remota.

iac-code a2a-client --config a2a-client.yml discover

Opción	Descripción
`--url`	URL base del agente A2A; puede venir de la configuración
`--verify-card-secret`, `--signing-secret`	Secreto HMAC para verificación
`--verify-card-jwks-url`	URL JWKS remota para verificación
`--require-card-signature`, `--require-signature`	Requerir una firma válida

Descubrimiento autenticado:

iac-code a2a-client --config a2a-client.yml discover

Comandos de tareas

Los comandos de tareas llaman directamente a métodos de tarea JSON-RPC. Son útiles para herramientas operativas, paneles y depuración.

`iac-code a2a-client task-get`

iac-code a2a-client --config a2a-client.yml task-get \
  --task-id task-123 \
  --history-length 20

Opción	Descripción
`--url`	URL del endpoint A2A JSON-RPC; puede venir de la configuración
`--task-id`	ID de tarea; puede venir de la configuración
`--history-length`	Entradas máximas de historial de tarea que devolver

`iac-code a2a-client task-list`

iac-code a2a-client --config a2a-client.yml task-list \
  --context-id ctx-123 \
  --status TASK_STATE_INPUT_REQUIRED \
  --page-size 20 \
  --output table

Opción	Predeterminado	Descripción
`--url`	vacío	URL del endpoint A2A JSON-RPC; puede venir de la configuración
`--context-id`	vacío	Filtrar por ID de contexto
`--status`	vacío	Filtrar por estado de tarea
`--page-size`	vacío	Máximo de tareas que devolver
`--page-token`	vacío	Token de paginación
`--include-artifacts`	`false`	Incluir artefactos de tarea en la respuesta
`--output`	`table`	`table` o `json`

Salida JSON:

iac-code a2a-client --config a2a-client.yml task-list \
  --include-artifacts \
  --output json

`iac-code a2a-client task-cancel`

iac-code a2a-client --config a2a-client.yml task-cancel \
  --task-id task-123

La cancelación es cooperativa. Una tarea completada, fallida, cancelada o que requiere entrada devuelve el error estándar A2A de tarea no cancelable.

`iac-code a2a-client task-subscribe`

iac-code a2a-client --config a2a-client.yml task-subscribe \
  --task-id task-123

El comando transmite eventos para tareas activas. Para un nuevo turno, prefiere a2a-client call --stream; inicia la tarea y transmite actualizaciones en un solo comando.

Comandos de configuración de notificaciones push

Estos comandos requieren un servidor iniciado con push-notifications: true. Gestionan configuraciones estándar de notificaciones push de tareas A2A.

`iac-code a2a-client push-config-create`

iac-code a2a-client --config a2a-client.yml push-config-create \
  --task-id task-123 \
  --config-id webhook-1 \
  --callback-url https://hooks.example.com/a2a \
  --notification-token "$NOTIFICATION_TOKEN" \
  --auth-scheme bearer \
  --auth-credentials "$WEBHOOK_BEARER_TOKEN"

Opción	Descripción
`--url`	URL del endpoint A2A JSON-RPC; puede venir de la configuración
`--task-id`	ID de tarea; puede venir de la configuración
`--config-id`	ID de configuración push; puede venir de la configuración
`--callback-url`	URL de callback HTTP(S); puede venir de la configuración
`--notification-token`	Token enviado como `X-A2A-Notification-Token`
`--auth-scheme`	Esquema de autenticación del callback, como `bearer` o `basic`
`--auth-credentials`	Credenciales de autenticación del callback

Las URL de callback se validan antes del almacenamiento y del despacho. El validador predeterminado rechaza URL que no sean HTTP(S), nombres localhost y direcciones IP literales privadas/locales.

`iac-code a2a-client push-config-get`

iac-code a2a-client --config a2a-client.yml push-config-get \
  --task-id task-123 \
  --config-id webhook-1

`iac-code a2a-client push-config-list`

iac-code a2a-client --config a2a-client.yml push-config-list \
  --task-id task-123 \
  --page-size 10

`iac-code a2a-client push-config-delete`

iac-code a2a-client --config a2a-client.yml push-config-delete \
  --task-id task-123 \
  --config-id webhook-1

`iac-code a2a-client extended-card`

Obtiene la Agent Card extendida autenticada.

iac-code a2a-client --config a2a-client.yml extended-card \
  --token "$A2A_TOKEN"

La Agent Card pública anuncia capabilities.extendedAgentCard=true. La tarjeta extendida agrega detalles autenticados del runtime, incluidos metadatos de capacidades de gestión de tareas y configuración push.

`iac-code a2a-route-preview`

Previsualiza cómo a2a-client call resuelve rutas configuradas cuando --url se omite.

iac-code a2a-route-preview \
  --route "template=http://127.0.0.1:41242/;skills=iac_generation;tags=ros,template" \
  --skill iac_generation \
  --prompt "Create a ROS VPC template"

Opción	Descripción
`--route`	Especificación de ruta repetible en formato `name=url;skills=a,b;tags=x,y`
`--name`	Nombre de ruta que resolver
`--skill`	ID de skill que resolver
`--prompt`	Texto de prompt usado para coincidencia de nombre/etiqueta
`--route-state-dir`, `--persistence-dir`	Directorio usado para persistir instantáneas de rutas
`--save-routes`	Guardar las rutas proporcionadas en el directorio de estado de rutas

Guardar instantáneas de rutas:

iac-code a2a-route-preview \
  --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
  --route-state-dir ~/.iac-code/a2a \
  --save-routes

Llamar mediante rutas:

iac-code a2a-client call \
  --route "ros=http://127.0.0.1:41242/;skills=iac_generation;tags=ros" \
  --route-name ros \
  --prompt "Create a ROS VPC template." \
  --cwd "$PWD"

Variables de entorno

Variable	Descripción
`IACCODE_A2A_HTTP_TOKEN`	Valor predeterminado del token Bearer de servidor/cliente
`IACCODE_A2A_BASIC_USERNAME`	Valor predeterminado del nombre de usuario de Basic auth de servidor/cliente
`IACCODE_A2A_BASIC_PASSWORD`	Valor predeterminado de la contraseña de Basic auth de servidor/cliente
`IACCODE_A2A_API_KEY`	Valor predeterminado de clave de API de servidor/cliente
`IACCODE_A2A_API_KEY_HEADER`	Nombre predeterminado del encabezado de clave de API
`IACCODE_A2A_ALLOWED_CWDS`	Lista separada por rutas del sistema operativo de raíces de espacio de trabajo permitidas para metadatos de mensajes entrantes y URL de archivos
`IACCODE_A2A_TEXT_MIME_TYPES`	Tipos MIME extra similares a texto separados por comas o punto y coma
`IACCODE_A2A_MULTIMODAL_MIME_TYPES`	Tipos MIME multimodales extra separados por comas o punto y coma
`IAC_CODE_A2A_PUSH_KEYRING`	Keyring de secretos push cifrados gestionado por el entorno

Resumen de comandos​

Configuración del cliente A2A​

iac-code a2a​

Opciones básicas del servidor​

Configuración YAML​

Autenticación HTTP​

Persistencia y artefactos​

Firma de Agent Card​

Entrega de notificaciones push​

Opciones de transporte​

Exposición de thinking​

Comportamiento de permisos​

iac-code a2a-client call​

iac-code a2a-client discover​

Comandos de tareas​

iac-code a2a-client task-get​

iac-code a2a-client task-list​

iac-code a2a-client task-cancel​

iac-code a2a-client task-subscribe​

Comandos de configuración de notificaciones push​

iac-code a2a-client push-config-create​

iac-code a2a-client push-config-get​

iac-code a2a-client push-config-list​

iac-code a2a-client push-config-delete​

iac-code a2a-client extended-card​

iac-code a2a-route-preview​

Variables de entorno​