Configure an agent
Open a company in HQ Console, choose Agents, then choose the Settings gear for an agent. Agent Settings keeps the full operating picture in one compact workspace:
- Configuration contains profile and model values that save together.
- Controls contains access, capacity, and runtime actions that apply immediately.
- Live systems contains health signals and expandable connection managers.
Most explanatory copy lives behind the help icon beside each section, leaving the values and current state visible at a glance.
Editing efficiently
Choose a configuration value to edit it in place. Only one editor or picker stays open at a time. Clicking elsewhere closes the open editor while keeping its draft staged for Save; pressing Escape cancels that field’s current edit instead. The footer tells you whether there are unsaved configuration changes, and Save remains disabled until a staged value differs from the saved configuration.
Connection rows and the Agent size row expand in place. Clicking elsewhere collapses the open panel without changing anything. Actions labeled Applies now do not wait for the configuration Save button and show their own confirmation when the change is consequential.
Configuration reference
| Setting | Purpose | Notes |
|---|---|---|
| Handle | Stable agent identifier | Chosen during creation. It is used in company identity, email, and vault paths and is not a normal profile edit. |
| Display name | Human-readable name shown in HQ and connected channels | The Console enforces channel-safe length limits. |
| Avatar | Profile image | HQ validates the image and file size before saving. |
| Title | Short role label | Use a role people can recognize, such as Research Lead. |
| Description | One-line responsibility statement | State what the agent owns and when teammates should contact it. |
| Provider | Runtime family | Selected at creation from the providers enabled for your account. Provider migration is not available in general Agent Settings. |
| Model | Model used for new work | Must be compatible with the provider and authentication method. |
| Reasoning effort | Depth used for supported models | Console values are Low, Medium, High, and Extra high. Grok does not use this setting. |
| Speed | Standard or Fast service tier | Available for supported Codex configurations. Fast can increase provider cost. |
| Membership role | Company permissions granted to the agent | An agent can be a member or admin, but cannot become the company owner. |
| Owners | People responsible for the agent | The creator is the initial owner. Additional ownership is shown only when enabled for the company. |
| Groups | Company groups the agent belongs to | Use groups for organization and policy-driven access. |
| Agent size | Runtime capacity and concurrency | Shows the current size, lanes, workers, and company-specific monthly price. Open the picker to compare Basic, Power, and Dev. See Agent sizes and billing. |
| HQ MCP | Agent connection to HQ tools and context | Owners and admins manage it under Integrations > For Agents while the runtime is running. |
| Slack | Slack app connection and diagnostics | Attach, finish a pending install, inspect delivery, or intentionally detach the app. |
| Telegram | Telegram bot connection and caller group | Connect a managed bot or supply a token, then choose who can call it. |
| Runtime controls | Start, stop, reauthenticate, or remove | Removal deprovisions the agent and requires confirmation. |
Model compatibility
HQ validates the model name against the selected provider:
- Codex supports OpenAI model families such as
gpt-*ando*. - Grok supports
grok-*models. - Claude supports Anthropic model families such as
claude-*,sonnet,opus, andhaiku.
The available list is the source of truth for your account. For Codex with ChatGPT subscription authentication, Agent Settings recommends gpt-5.6-sol; Sol is supported wherever it is available to the signed-in ChatGPT account. Only models whose names end in -codex require OpenAI API-key authentication. Agent Settings filters incompatible choices and returns an actionable message if a saved value does not match the agent’s authentication method. The Console also prevents model and reasoning combinations that the runtime cannot honor.
Profile guidance
A useful agent profile answers three questions:
- What does this agent own?
- What requests should teammates send it?
- What should a teammate do when the request is outside its scope?
Keep the title short and make the description operational. Channel users should be able to decide whether to mention the agent without opening HQ Console.
Managed settings
Changing an agent’s box size is a confirmed billing action available from Agent Settings — see Agent sizes and billing. The backend also supports lower-level controls for autoscaling, caller email allowlists, provider migration, and direct MCP state. These are API or control-plane fields, not standard Agent Settings controls. An invalid value can prevent the runtime from starting or reject channel callers.
Credentials are stored as vault references. Raw provider keys and channel tokens are never returned by the settings API.