Agent Engines

An agent engine runs a conversation using its own agent loop: it decides how to respond, which tools to call, and how to continue its session. Posit Assistant supplies its tools, instructions, and conversation context, and displays the engine’s responses and tool calls.

Engines are different from model providers. Choosing a provider’s model keeps Posit Assistant’s built-in agent loop. Choosing an engine replaces that loop. For example, GitHub Copilot as a provider supplies models to Posit Assistant; GitHub Copilot Agent runs Copilot’s own agent. Connecting one does not connect the other.

Connect and select an engine

1. Open Configure AI Providers. In Positron, run Posit Assistant: Configure AI Providers from the Command Palette or open it from the Accounts menu. In RStudio and Standalone, choose Configure AI providers from the assistant’s More actions menu.
2. Find Agent engines and select Connect next to the engine you want. Complete the engine’s setup below, then select Connect in its dialog. For an external ACP agent, use Add ACP agent instead.
3. Wait for the connection check. A successful check returns to the list; a failed check stays open with a reason. Some routes show sign-in checked on first use, rather than verified authentication.
4. Open the model picker in the chat status bar. Engine groups appear after model providers. Select the engine and one of its model entries, then send a message.

You can use an engine without connecting a native model provider. Connecting an engine makes it available; selecting it in the picker chooses it for the conversation. Selecting a provider’s model switches back to Posit Assistant’s built-in agent. Selection is unavailable while a response is running.

Manage connections and keys

Action	Effect
Connect	Enables the engine, saves any entered key or ACP configuration, and checks the connection.
Save	Updates a key or ACP configuration without turning a disabled engine on. An enabled engine is checked again.
Disconnect	Turns the engine off but keeps its saved key and configuration. It is not an account sign-out.
Remove key	Deletes the saved engine key. It does not disable the engine or remove environment credentials or CLI logins.

Claude Agent and Codex Agent keys are stored separately from the Anthropic and OpenAI provider keys. Enter them in the engine’s dialog, even if you already configured the corresponding provider. Keys entered here use the host’s credential store, not providers.json.

A blank key field keeps the saved key; it does not clear it. A saved engine key takes precedence over environment credentials. Use Remove key to fall back to another authentication route. For an ACP agent you added, Remove agent deletes its entry from providers.json.

Engine setup

For the three built-in engines, Posit Assistant finds or downloads the required executable on the first connection check or session start. You do not normally need to install their CLIs yourself. Downloads use registry.npmjs.org and are allowed by default; an administrator can disable them. An explicitly configured executable path must exist—an invalid path does not fall back to a download.

Claude Agent

Get an Anthropic API key, enter it in the Claude Agent dialog, and select Connect. Alternatively, start Posit Assistant with ANTHROPIC_API_KEY in its environment and leave the key field blank.

The built-in Claude Agent does not use a Claude subscription sign-in or CLAUDE_CODE_OAUTH_TOKEN. Cloud authentication, such as Bedrock or Vertex AI, requires the Claude Agent’s own environment configuration; configuring a model provider alone does not configure the engine. The dialog’s key form is for Anthropic’s API.

The picker currently offers Claude Agent’s default model, not the full Anthropic provider catalog.

Codex Agent

The simplest route is an OpenAI API key: enter it in the Codex Agent dialog and select Connect. Without a saved engine key, Posit Assistant checks OPENAI_API_KEY, then CODEX_API_KEY, in its own environment.

ChatGPT sign-in

Codex can also use a ChatGPT sign-in, but it must be in the engine’s CODEX_HOME, not the CLI’s usual ~/.codex directory. There is no ChatGPT sign-in button in Posit Assistant.

For Positron, RStudio, and a local single-user Standalone installation using default storage and no agentEngines.codex.homeDirectory override, the engine home is ~/.posit/assistant/engines/codex-agent. With the Codex CLI installed on your terminal’s PATH, run this on the machine and as the account that runs Posit Assistant. If you need the CLI, follow OpenAI’s Codex CLI installation guide.

CODEX_HOME="$HOME/.posit/assistant/engines/codex-agent" codex login

In Windows PowerShell, use:

$env:CODEX_HOME = "$HOME/.posit/assistant/engines/codex-agent"
codex login

If the executable is not on PATH, use its full path instead of codex; Posit Assistant’s managed download does not install a terminal command. For remote IDE sessions, use a terminal on the remote machine, not your local computer.

Then Remove key in the Codex Agent dialog and remove OPENAI_API_KEY and CODEX_API_KEY from the environment that launches Posit Assistant if you want the ChatGPT route. Restart the host after changing its launch environment, and use Check now or Check again.

With custom Standalone storage, the default engine home is engines/codex-agent beneath that storage root. An explicit agentEngines.codex.homeDirectory changes it; ~/.codex itself is not accepted and falls back to the engine-specific default. The not-signed-in error gives the actual home to use. If you cannot establish the correct home—for example, on a managed shared server—use the API-key route or ask the operator rather than guessing a login path.

GitHub Copilot Agent

Use a GitHub account with access to Copilot.

• Positron: use Sign in to GitHub in the engine configuration, or Change account once connected. The account picker also offers Use GitHub CLI sign-in.
• RStudio and Standalone: install GitHub CLI and run gh auth login as the account running Posit Assistant, then connect the engine. Alternatively, supply COPILOT_GITHUB_TOKEN or GH_TOKEN in Posit Assistant’s launch environment.

A selected Positron GitHub account takes precedence over CLI or environment sign-in. If that account becomes unavailable, the engine does not silently switch to another route. Use the account picker to choose again.

Do not rely on a separate copilot login: the built-in engine uses a different Copilot data directory from the CLI’s default. Use the IDE account, gh, or a token variable instead.

ACP agents

The Agent Client Protocol (ACP) connects an external agent process to Posit Assistant. Install and authenticate the agent before adding it. Posit Assistant does not install ACP agents or run their interactive authentication flow.

1. Select Add ACP agent under Agent engines.
2. Choose a preset—OpenCode, Google Antigravity, Claude Code, Codex, or Copilot CLI—or Custom. Presets fill in a starting command and arguments, not an installation.
3. Check Command: use a program on the backend’s PATH or its full path. Enter each Argument separately, including the argument that starts ACP mode.
4. Review the permission warning, then select Add. Send a message to check that the agent can actually authenticate and start a session.

For example, the OpenCode preset runs opencode with the argument acp. The Claude Code and Codex presets require the separate claude-agent-acp and codex-acp adapters. Google Antigravity requires its separate ACP server and authentication configuration. Follow each preset’s setup note; the ordinary agent CLI may not provide ACP mode itself.

An ACP connection check only starts the process and checks the protocol. It does not prove authentication works. ACP agents currently appear as a single picker entry; choose their underlying model through the agent’s own configuration, not Posit Assistant’s provider list.

Permissions and security

Posit Assistant’s permissions and tool hooks apply when an engine calls Posit Assistant’s tools. The built-in Claude, Codex, and Copilot adapters also route their supported engine-owned tool calls through Posit Assistant’s permission handling, but do not assume every engine has the native agent’s capabilities.

Posit Assistant’s PreToolUse and PostToolUse hooks do not run for ACP-owned tools; they still run for Posit Assistant tools called by the agent. Engine turns do not currently fire Posit Assistant’s Stop hook.

ACP Environment variables are saved as plaintext in providers.json. Do not put secrets in that form or in copied configuration examples. Use the agent’s own authentication setup.

Shared servers

On a shared multi-user server, engine configuration and keys are managed by the operator; users see Details rather than editable connections. Enabled engines and operator-managed keys are offered to the server’s users. Per-user engine state directories do not provide per-user credential isolation: engines can use the server account’s environment and logins, and an ACP entry’s environment values apply to every user offered that agent.

Sessions and feature limits

• Models and attachments: available models and supported image, audio, or document types depend on the engine and selected model. The provider catalog is not the engine catalog.
• Compaction: the engine owns its transcript and context management. Posit Assistant’s auto-compaction and /compact do not apply to engine conversations. /microcompact only changes Posit Assistant’s saved conversation; it does not shrink the engine’s context.
• Branching and edits: continuing from an earlier turn requires engine support. ACP agents cannot currently branch at a turn. When continuation is unsupported, edit/resend controls are disabled with an explanation. See Conversations.
• Recovery: an engine may resume after a host restart, but this depends on the engine and its stored session. If the session is missing, cannot resume, or no longer agrees with the displayed history, the notice above the chat input offers Start a new engine session. This starts over with a summary of the conversation; it does not restore the old transcript.
• Switching: moving from the native agent to an engine starts a seeded engine session. Switching back to a provider model is best effort, not guaranteed lossless continuation; start a new conversation if mixed history causes problems.
• Other native features: the native web-search toggle and /recall are not available for engine turns. Context-window usage depends on what the engine reports, and engine usage is not a complete cost estimate. An unmeasured token counter cannot tell you when an engine needs compaction.

Troubleshooting

Symptom	What to check
No Agent engines section	Check the host and Positron build requirement above. A server deployment that prohibits shell execution does not offer engines.
Engine missing from the picker	Connect it first. Check whether it is disabled or administrator-controlled. All built-in engines start disabled.
Connection or sign-in fails	Read the dialog’s reason and use Check now or Check again after fixing it. Check engine-specific credentials, saved-key precedence, and the backend’s launch environment—not just the environment in a new terminal.
First check or turn is slow	The first use may download a large executable. A session-start download has no progress indicator; stopping the turn does not necessarily stop the download.
Download disabled, path missing, or SDK unavailable	Ask the operator to allow downloads or supply a valid executable path. An SDK-unavailable message requires a host/build that ships the SDK; an API key cannot fix it.
ACP connects but the first message fails	Authenticate the external agent and verify its ACP command and setup note. The connection check did not verify sign-in.
Session cannot continue	Use Start a new engine session above the chat input. If the engine was disabled, re-enable it or deliberately select a provider model; with a native model already selected, a disabled engine can fall back to it.

Engine enablement, executable paths, download policy, and ACP definitions live in the agentEngines block of global providers.json, not ~/.posit/assistant/settings.json or project settings. Administrator policy may keep an engine on or off, or make an ACP definition read-only. The preview block is described in the hosted JSON schema, but is not included in the generated provider settings reference.