iai agents update

Update an agent in a project

Synopsis

Update an agent in a specific project.

Only the flags you pass are applied; everything else is left at its current value.

--file takes a YAML file matching the agent_config schema and replaces the entire agent config in full when provided (no per-field merge). The config schema depends on the agent version — run 'iai agents compatibility-matrix' to find which schema version applies, then 'iai agents schema --schema-version ' to see the expected fields.

When upgrading to a new agent version with a different schema, update your routines and policies first using --schema-version on their create/update commands, then update the agent with the new config and version.

Lists (--env, --secret) replace their user-managed values when provided — pass every value you want to keep. Env names starting with IAI_MCP_ or MCP_KEY_ are reserved.

For schedules, passing --schedule-uptime auto-clears any existing downtime, and --schedule-downtime auto-clears any existing uptime. Pass --schedule-timezone alongside either to change the timezone.

Use --clear-env, --clear-secret, --clear-schedule, or --clear-stack-id to remove those configurations entirely.

Before applying, the CLI prints deploy-awareness output to stderr: the live revision this update replaces; the names of any env vars or secret refs that --env/--secret would drop from the live agent (the flags replace the entire list); and — when the update replaces the agent config — a summary of content pin changes (a stale local manifest silently reverts colleagues' work). The update is refused when it would downgrade or remove a live content pin, or drop live env vars or secret refs via --env/--secret; pass --force to apply anyway. --clear-env and --clear-secret never trigger the gate: clearing is explicit intent. Changes in unrecognized pin-shaped config sections warn without blocking. The checks fail open when live state cannot be fetched; use --expect-revision to fail instead when the live revision differs from what you expect, and --show-diff for a full live-vs-incoming config diff.

iai agents update <agent_name> [flags]

Examples

  iai agents update chat-agent --version 0.0.3
  iai agents update chat-agent --file agent-config.yaml
  iai agents update chat-agent --file agent-config.yaml --expect-revision 13
  iai agents update chat-agent --file agent-config.yaml --show-diff
  iai agents update chat-agent --endpoint=false
  iai agents update chat-agent --schedule-uptime "Mon-Fri 07:30-20:30" --schedule-timezone Europe/Berlin
  iai agents update chat-agent --clear-schedule
  iai agents update chat-agent --stack-id my-stack
  iai agents update chat-agent --clear-stack-id
  iai agents update chat-agent --mcp github
  iai agents update chat-agent --mcp tools-dev --mcp-id tools
  iai agents update chat-agent --mcp tools-dev --mcp-endpoint public
  iai agents update chat-agent --detach-mcp stripe

Options

      --clear-env                  Remove all environment variables from the agent
      --clear-schedule             Remove the schedule configuration from the agent
      --clear-secret               Remove all secret references from the agent
      --clear-stack-id             Remove the agent from its stack
      --detach-mcp stringArray     Detach an MCP by name, whatever prefix it has; can be repeated. Without --file, removes from the agent's current mcps, before --mcp, so both together swap one for another. Detach an MCP before deleting it: 'iai mcps delete' blocks while an agent still references it
      --endpoint                   Expose the agent publicly at <agent-name>-<project-hash>.interactive.ai
      --env stringArray            Environment variable (NAME=VALUE); can be repeated
      --expect-revision int        Fail without applying unless the live revision equals this value; 0 is valid and matches a never-updated agent (opt-in staleness guard)
      --file string                Path to YAML file matching the agent_config schema (run 'iai agents schema' to see it)
      --force                      Apply even when the update would downgrade/remove live content pins or drop live env vars or secret refs
  -h, --help                       help for update
      --id string                  Agent type from the marketplace (e.g. interactive-agent)
      --mcp stringArray            Attach one MCP by name (see 'iai mcps list'); attach further MCPs in their own commands. Without --file, appends to the agent's current mcps; an MCP already attached keeps its prefix and endpoint unless --mcp-id or --mcp-endpoint set them
      --mcp-endpoint string        Endpoint this agent dials the MCP on: private (default, reachable only within the project) or public (the MCP's public endpoint; needs a self-hosted MCP with it enabled); needs exactly one --mcp
      --mcp-id string              Prefix this agent calls the MCP's tools by, as in 'tools:send_email' (defaults to its name; pass its name to go back to that), so MCPs such as tools-dev and tools-prod can share a prefix and routines; needs exactly one --mcp
  -o, --organization string        Organization name
  -p, --project string             Project name
      --schedule-downtime string   When the agent should be scaled down (mutually exclusive with --schedule-uptime). Format: comma-separated entries of DAY_FROM-DAY_TO HH:MM-HH:MM. Example: 'Sat-Sun 00:00-24:00'
      --schedule-timezone string   IANA timezone for the schedule (e.g. Europe/Berlin, US/Eastern, UTC); required with --schedule-uptime or --schedule-downtime
      --schedule-uptime string     When the agent should be running (mutually exclusive with --schedule-downtime). Format: comma-separated entries of DAY_FROM-DAY_TO HH:MM-HH:MM. Example: 'Mon-Fri 07:30-20:30'
      --secret stringArray         Secret to inject as environment variables; can be repeated
      --show-diff                  Print a live-vs-incoming agent config diff to stderr before applying; requires --file, --mcp, or --detach-mcp
      --stack-id string            Stack ID to assign the agent to
      --version string             Agent image version to deploy (e.g. 0.0.1)

Options inherited from parent commands

      --api-key string               API key for authentication
      --cfg-file string              Path to YAML config file with organization, project, and optional service definitions
      --deployment-hostname string   Hostname for the deployment API (default "https://deployment.interactive.ai")
      --hostname string              Hostname for the API (default "https://app.interactive.ai")

SEE ALSO

• iai agents - Deploy AI agents with policies, routines, and tools