> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Ask Oqo as a custom agent

> Run Ask Oqo in experiments as a custom agent from a CLI download, with a personal API key as its sign-in, and measure how well it answers.

> [!NOTE]
>
> Custom agents are in private beta. Email [support@oqoqo.ai](mailto:support@oqoqo.ai) to enable them for your organization.

Evaluate how accurately [Ask Oqo](https://docs.oqoqo.ai/operate/ask-oqo.md) answers questions about your Oqoqo projects by connecting `oqoqo acp ask-oqo` as a [custom agent](https://docs.oqoqo.ai/setup/custom-agents.md) and grading its responses with tasks and rubrics.

## Prerequisites

* [Ask Oqo](https://docs.oqoqo.ai/operate/ask-oqo.md) works in the dashboard (has an **Ask Oqo model** assigned and you opened Ask Oqo once to initialize your chat connection).
* Target project ID (`oqoqo projects current` or `/projects/prj_…` in the dashboard URL)—prefer a dedicated fixture project if tasks ask Ask Oqo to modify records, or set **Max Concurrency** to `1`.

> [!WARNING]
>
> The personal API key acts as your user account in every run of this custom agent, including runs launched by teammates. Those runs can read and modify your projects and appear in your Ask Oqo chat history.

## Steps

**1. Create a personal API key**

Because cloud runs cannot complete browser OAuth, open [**Profile → API keys**](https://docs.oqoqo.ai/setup/profile.md#api-keys) and create a personal key to pass via `OQOQO_API_KEY`.

**2. Get the Linux x64 CLI release**

Inspect the `latest.json` manifest URL inside the `https://oqoqo.ai/install` shell script and copy the `url` and `sha256` for `linux-x64`:

```bash theme={null}
curl -fsSL https://oqoqo.ai/install | grep -E "latest\.json|MANIFEST" | head -n 5
```

Open that `latest.json` URL to read the `linux-x64` `url` and `sha256` (pinned downloads do not auto-update; update these fields to test newer CLI builds).

**3. Connect the custom agent**

Under **Manage → Agents**, select **Connect custom agent** with:

| Field | Value |
| - | - |
| **Name this agent** | `Ask Oqo` |
| **Install** | **Download** |
| **Download URL** | `linux-x64` `url` from `latest.json` |
| **SHA-256** | `linux-x64` `sha256` from `latest.json` |
| **Command** | `oqoqo` |
| **Arguments** | `acp ask-oqo --project-id <project-id>` |

Under **Environment variables**, add `OQOQO_API_KEY` with your personal key, then select **Connect agent**.

**4. Test the agent**

Select **Test agent** so Oqoqo verifies startup and discovers Ask Oqo's available models. Once **Status** reaches **Ready**, enable the models you want to compare under **Models**.

| Error if Needs attention | Fix |
| - | - |
| Invalid or revoked API key | Generate a new personal key for `OQOQO_API_KEY`. |
| Ask Oqo is not connected | Open Ask Oqo once in the dashboard, then retest. |
| SHA-256 mismatch | Recopy `url` and `sha256` from the same `linux-x64` entry. |
| CLI version refused | Update **Download URL** and **SHA-256** to the latest `linux-x64` build. |

**5. Write tasks about your Oqoqo projects**

Because Ask Oqo calls Oqoqo APIs directly rather than reading files or tools inside the run container, write [tasks](https://docs.oqoqo.ai/experiments/tasks.md) asking about your project (such as *"How many tasks does this project have?"*) with rubrics grading the reply.

**6. Launch the experiment**

Open **New experiment**, select your tasks, choose **Ask Oqo** with the models to compare, keep **Raw Agent** (treatment tools do not reach Ask Oqo), and select [**Launch**](https://docs.oqoqo.ai/experiments/launch.md).

## Interpret the results

Compare pass rates (**Evals**), **Cost**, **Tokens**, and **Duration** on **Matrix** across models to pick the best **Ask Oqo model** under **Oqoqo AI defaults**. If every model fails a task, inspect **Traces** to see which Oqoqo tools Ask Oqo called; startup failures appear under **Custom agent** in **Frictions**.

## From the CLI and the plugin

Create the custom agent headlessly, open the returned `setupUrl` in the dashboard to enter `OQOQO_API_KEY`, and then run **Test agent**:

```bash theme={null}
oqoqo project ai apply --operation '{"action":"create_custom_agent","name":"Ask Oqo","source":{"kind":"manual","install":{"kind":"download","url":"<linux-x64 url>","sha256":"<linux-x64 sha256>","command":"oqoqo"},"args":"acp ask-oqo --project-id <project-id>"},"env":["OQOQO_API_KEY"]}' --output json
oqoqo project ai test-agent <agent-key>
```

From the plugin, pass the same payload to [`manage_project_ai`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_project_ai) and run [`test_custom_agent`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#test_custom_agent).

## Next steps

> [card] [Custom agents](https://docs.oqoqo.ai/setup/custom-agents.md)
>
> Connect any ACP agent from npm, Python, downloads, or the registry.

> [card] [Ask Oqo](https://docs.oqoqo.ai/operate/ask-oqo.md)
>
> Configure Ask Oqo in the dashboard, Slack, and editors.

> [card] [Use an API key](https://docs.oqoqo.ai/operate/cli.md#use-an-api-key)
>
> Authenticate the CLI with `OQOQO_API_KEY`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.