Configura agentes, presets, transporte

Detecta los CLIs de agentes instalados, elige presets de lanzamiento, y decide como se autentica y se comunica cada uno con orch.

Objetivo#

Decirle a orch que CLIs de agentes de codigo hay en tu maquina, como lanzar cada uno (despacho headless vs. TUI nativo), que credenciales debe usar, y — para los pocos que lo soportan — como manejarlo via Agent Client Protocol (ACP) en vez de leer un pipe de subproceso.

Pasos#

Escanea tu PATH buscando CLIs de agentes conocidos (Claude, OpenCode, Cursor, Codex, Copilot, …):
```
orch agents scan
```
Escribe un snapshot; todavia no toca orch.yaml.
Revisa que se encontro:
```
orch agents show
```
Aplica las nuevas detecciones a orch.yaml (nunca sobrescribe presets que ya editaste):
```
orch agents apply
```
Los presets viven en dos mapas dentro de orch.yaml:
- agents.cmds.<preset> — plantilla headless BYO usada por los workers despachados, ej. claude -p "{{prompt}}". Vienen incorporados copilot, claude, opencode, grok, kimi, commandcode, agy, codex y cursor.
- agents.interactive.<preset> — lanzamiento de TUI nativo usado por orch <preset> (no requiere prompt), ej. codex, cursor-agent, claude, opencode --hostname 127.0.0.1 --port {{notify_port}}.
Edita cualquiera de los dos mapas directamente en orch.yaml para agregar un CLI que orch no conoce, o para cambiar una plantilla existente. Si despachas un preset de CLI reconocido que no tiene entrada agents.cmds.<preset>, orch falla en voz alta hacia el Chair (preset "<preset>" has no headless command: set agents.cmds.<preset>) en vez de correr el agente stub en silencio — agrega la entrada para resolverlo.
Elige el modo de credenciales por preset con agents.auth.<preset>:
- account — el agente mantiene su propio login de plan; orch solo inyecta sus propias variables ORCH_GATEWAY_*, nunca claves de proveedor.
- gateway — el agente se autentica con la llave virtual de orch y todo el trafico de modelos pasa por el gateway local.
Por defecto: codex y cursor son account (forzar credenciales ahi les quitaria los conectores de la suscripcion). claude es gateway solo cuando hay una llave passthrough de Anthropic configurada, si no es account. Todo lo demas es gateway por defecto.
Para los CLIs que exponen un modo servidor Agent Client Protocol — actualmente gemini (gemini --acp) y opencode (opencode acp) — configura:
```
agents:
  transport:
    gemini: acp
```
ACP hace visibles para orch las llamadas a herramientas y los prompts de permiso, en vez de leer stdout. Cualquier otro preset se queda en el transporte subprocess por defecto; agents.acp.<preset> guarda la invocacion que orch corre para poner ese CLI en modo ACP (incorporada para gemini/opencode, vacia para el resto — un preset sin entrada ACP no puede usar transport: acp).

Define los limites de ejecucion:

agents:
  timeout_sec: 600        # tope de reloj por ejecucion (0 = default)
  idle_timeout_sec: 0     # mata si no hay stdout/stderr por este tiempo; 0 = apagado

Verificar#

orch <preset>

lanza el TUI nativo de ese preset. Para un despacho headless, revisa .orch-agent.log en el worktree de la sesion para ver el comando resuelto y cualquier codigo de salida por permiso/timeout (124 = agents.timeout_sec/idle timeout, 126 = un prompt de permiso headless que orch no pudo responder).

Deshacer#

Quita la entrada del preset de agents.cmds / agents.interactive, o regresa agents.auth.<preset> / agents.transport.<preset> a sin definir para volver a los valores por defecto de arriba.

Relacionado#

gateway-keys-and-connect.md — que es lo que realmente enruta agents.auth: gateway.
troubleshooting.md — timeouts de permiso en workers.