Three ways to work
A code agent is read-only in Console (“Managed by code”). An organization owner can move it to Console; code deploys are then refused. Export as YAML in Console gives you a Console agent’s file to move it into Git.
Name the agent when a chat starts
instructions are added after the agent’s, never replacing them:
agentOverrides: "reject" to refuse any change instead (422 agent_override_rejected). With the session proxy, name the agent in your createSession hook; an agent sent by the browser is dropped.
Chats read back which agent and version they run in session.orgAgent.
Agent files
One file per agent, named after its key:Runs on
The machine or Sandbox Environment must be your organization’s and available in the workspaces your product manages: turn on All product-managed workspaces in Available in. A deploy that names an unknown machine or environment fails with
machine_not_found or environment_not_found; Personal (Only me) machines can’t be used. A chat can still pass sandboxBackend, targetSandboxId or rigId; that is recorded as a change by the chat. A Personal machine never runs these chats, whether a request, a default or a worker’s parent chat puts it there (personal_machine_not_allowed). A deployed version keeps the machine or environment by id, so renaming it or adding another with the same name doesn’t move the agent.
Deploy
created, updated or unchanged, the version, whether it is published, and its config hash. Deploying unchanged files is a no-op. --dry-run writes nothing, says would create vN or unchanged for each agent and prints its diff against its published version; an instructions file that doesn’t exist is an error. Add --move-running-chats with --publish to move running chats to the new version too, and --json for machine-readable output. npx opengeni agents export <key> --out agents writes an existing agent’s file.
From GitHub Actions: