OpenAI Agents

Deliver Briefs through your OpenAI Platform account, with OpenAI's hosted sandbox running the agent and Hamster tracking the delivery.

Overview

The OpenAI Agents connection lets Hamster delegate Brief deliveries to OpenAI Agents on your connected OpenAI Platform account.

OpenAI owns the hosted sandbox and the model run. OpenAI bills the usage to the connected key's project. Unlike Hamster Cloud, OpenAI Agents doesn't need a Team or Enterprise plan.

Hamster gives the agent access to the Brief's repository and its Plan, shows the run in the delivery thread, and opens the pull request.

How It Works

  1. Connect the OpenAI Platform key whose project will run deliveries.
  2. Connect the repository through your team's GitHub connection. OpenAI Agents delivers only to GitHub repositories. Use Hamster Cloud for repositories on GitLab or Cursor Origin.
  3. Open the chevron beside Deliver on the Brief and choose OpenAI Agents. Hamster runs the same first-delivery and pre-flight steps as other methods, then starts the delivery with the model and pull request setting from your delivery settings. Follow progress in the delivery thread.
  4. Review the draft pull request that Hamster opens. On GitHub, click Ready for review, then merge it.

How to Connect

  1. Create an API key at platform.openai.com/api-keys in the project that should pay for deliveries. Give it the api.agents.read, api.agents.write, api.model.read, and api.responses.write scopes. Hamster uses api.model.read to list the models your key can run. Any key that starts with sk- works, including a project service account key. A ChatGPT account token does not work.
  2. Open the key dialog. If you can manage Connections, click the OpenAI Agents card in Knowledge > Connections. Otherwise, choose OpenAI Agents from the Deliver menu, or turn on Override team defaults in Personal settings > Delivery, choose OpenAI Agents as the Method, and click Connect on the Model card. These two entry points appear only when no key, yours or the team's, is available to you.
  3. Under Connect as, choose Yourself to keep the key private to you, or {team name} team to share it with everyone. The choice appears only if you can manage Connections. Otherwise the key is saved as yours. A key you connect from Personal settings > Delivery is always saved as yours.
  4. Paste the key into API Key and click Connect OpenAI Agents. If you connect from Knowledge > Connections, choose the team, and a team key is already saved, the button reads Replace team key instead.

Hamster tests the key with OpenAI before it saves it, and saves nothing if the test fails. A key that passes can still be missing the model or write scopes. That shows up when Hamster lists models or starts a delivery.

When you have your own key and the team also has one, your deliveries use your key.

Managing the Connection

A connected key appears as a card on Knowledge > Connections, marked Personal or Team. Your own key shows there even if you can't manage Connections.

To remove a key, right-click the card and choose Disconnect, then confirm Delete. You can remove your own key. Removing the team key requires permission to manage Connections.

  • Removing your own key affects only you. Your deliveries fall back to the team key if one exists.
  • Removing the team key stops teammates without their own key from delivering with OpenAI Agents.

Stop team-key deliveries before you remove or replace the team key. If a session was left running, end it in the OpenAI dashboard.

Models

Owners and admins set the team's model in Settings > Delivery: choose OpenAI Agents as the Method, then pick a model in the Model card. To use a different model yourself, turn on Override team defaults in Personal settings > Delivery. Switching to another method clears the saved model, because each method has its own models.

If you choose OpenAI Agents from the chevron while your delivery method is something else, that run uses GPT 6 Astra.

The list comes live from OpenAI through the connected key. It shows GPT 5.2 and newer GPT models your key can run, newest first. Codex, mini, and nano models aren't listed. A listed model can still be refused at launch.

GPT 6 Astra is the default. Deliveries use it whenever no OpenAI model is saved, and always when the delivery starts from chat. The provider default in the Model card's messages is GPT 6 Astra. If your key can't run GPT 6 Astra, the Model card shows Provider default instead of a model, and deliveries with no saved model fail at launch until you pick one.

If OpenAI refuses the saved model at launch, the delivery fails and asks you to pick another.

Delivery and Pull Requests

Each delivery runs in its own session in OpenAI's hosted sandbox. The agent reads the Brief and its Plan through Hamster MCP.

The agent works through the Plan one parent task at a time. Each task moves to In Progress when the agent starts it and to Done once its work lands, so the Plan updates as the run goes. A task the agent can't finish goes back to Todo, and the final report says why.

The agent pushes its work to a branch that starts with hamster/. When the run finishes, the delivery thread shows two cards. Pushing branch turns into Branch pushed: once the branch is on GitHub. Then Creating pull request turns into Draft pull request opened:, with a link to the draft pull request Hamster opened as the Hamster GitHub App and linked to the Brief. If a pull request is already open for the branch, Hamster reuses it. To push only the branch, turn off Pull request in your delivery settings. The thread then stops at Branch pushed:. The title and body use the same format as Hamster Cloud.

Use Reviewing Briefs to review the pull request in Hamster. Even though the Hamster GitHub App opens it, Hamster doesn't let you approve a pull request your own delivery opened. The pull request stays a draft, so on GitHub click Ready for review before you merge it.

An OpenAI Agents delivery doesn't change the Brief's status, and merging its pull request moves the Brief to Delivered only if it's already in Shipping, so move the Brief yourself. See Brief Status.

The agent's commits are unsigned. If the base branch requires signed commits, GitHub blocks merging the pull request until the commits are re-signed.

Steering and Stopping

Type in the delivery thread while the run is live to steer it. The composer reads Steer the agent... while the agent is running. Hamster queues your messages above the composer as Waiting for next prompt, with each message's place in line. Click Cancel on a queued message to drop it.

When the agent finishes its current step, it picks up the next waiting message. The run keeps the same branch, and Hamster opens the pull request after the last follow-up finishes. Hamster drops any messages still queued when the run ends, fails, or is stopped. If Hamster can't send a follow-up, the message shows Steering failed. Once the run ends, the composer says that the delivery ended and the agent is no longer running.

Hover the spinning Deliver button on the Brief, click the stop icon (Stop delivery), then click Accept in the Stop delivery? dialog. Hamster stops the run and confirms with Stopped. Tasks the agent changed go back to the status they had when the delivery started. No pull request opens. The delivery thread has no Stop button for OpenAI Agents runs.

If Hamster shows Couldn't stop it., try again, or end the session in the OpenAI dashboard. Already done. means the run had already finished.

If a Delivery Fails

Hamster names the cause whether the delivery fails before or during the run. If a delivery fails to start, hover Deliver on the Brief to read it. When Hamster gives up on a stuck or timed-out run, the error ends with Check the session in the OpenAI dashboard. When a delivery fails or you stop it, tasks the agent changed go back to the status they had when it started.

If you can't see the OpenAI Agents card in Knowledge > Connections, check whether a key is available to you. If none is, connect from the Deliver menu, or from Personal settings > Delivery with Override team defaults on. If the team has a key, your deliveries use it.

Before the Run

  • OpenAI Agents is greyed out in the Deliver menu: Another delivery on this Brief is still running, or a Hamster Cloud delivery on it is stopped or waiting for review. Merging or closing that delivery's pull request clears it. A Brief can have one active delivery at a time. If the chevron beside Deliver is disabled, the Brief is archived.
  • OpenAI Agents is not connected for this user. Connect a key as shown in How to Connect.
  • You do not have permission to use OpenAI Agents delivery: Delivering needs the Creator role or higher. Ask an owner or admin to change your role.
  • OpenAI Agents deliver GitHub repositories; other repositories deliver through the standard cloud delivery. The Plan's repository is on GitLab or Cursor Origin. Deliver it with Hamster Cloud, or deliver a GitHub repository.
  • Hamster's GitHub App cannot push to this repository. Check the app's repository access in GitHub. Give the Hamster GitHub App access to the repository from Manage or uninstall on GitHub on the GitHub card.
  • A message that starts with This plan is already delivered: No task in the Plan is Todo or In Progress, so Hamster does not start the run. Move a task back to Todo to deliver it again.

Key and Project

  • Invalid OpenAI API key format. Expected an OpenAI Platform key (sk-…). The connect dialog got a ChatGPT token or a partly copied key. Copy the full secret key from platform.openai.com/api-keys and paste it again.
  • OpenAI is temporarily unavailable. Try again. The key test couldn't reach OpenAI. Wait a moment, then connect the key again.
  • OpenAI rejected this API key. The key is wrong or was revoked. Create a new key and connect it again.
  • OpenAI rejected the connected key or its access: OpenAI refused the key during a run. The key was revoked or lost access to its project. Connect a working key, then deliver again.
  • This key lacks the scopes api.agents.read, api.agents.write, api.model.read, api.responses.write. Create a key with all four scopes and connect it again.
  • OpenAI Agents is not enabled for this key's organization or project. Enable the Agents API for that project on the OpenAI Platform, or connect a key from a project that has it.
  • The key's OpenAI project has no available quota or billing. Add billing or credits for that project on the OpenAI Platform. The same message appears when a run hits the project's spend or usage limit.
  • OpenAI organization spend limit exceeded. or OpenAI organization usage limit exceeded. Raise the organization's limit on the OpenAI Platform, then deliver again.
  • OpenAI could not validate this key. The key test failed for another reason. Check the key on the OpenAI Platform and try again.

Model Errors

If the key's project has no model OpenAI Agents can run, the Model card's list is empty and there's no model to pick. Check the project's model access on the OpenAI Platform.

  • OpenAI Agents is rate limiting model lookups. Reload this page in a minute. Deliveries use the provider default until then. OpenAI is limiting how often Hamster can list your models. Reload Settings > Delivery after a short pause.
  • You do not have permission to view OpenAI Agents models. Ask an admin or creator on this account. Viewing models needs the Creator role or higher. Ask an owner or admin to change your role.
  • The model list isn't available. Deliveries use the provider default until it loads. Hamster couldn't load the list on the Model card.
  • OpenAI Managed Agents cannot run the selected model with this key. Pick another model. The saved model isn't available to the key's project. Pick another model in Settings > Delivery, or in Personal settings > Delivery if you override the team defaults.

Outages

  • OpenAI Agents is temporarily unavailable. Try again in a few minutes. OpenAI's service is having trouble. Nothing on your side needs to change.
  • GitHub could not issue a push credential. Try again in a few minutes. A temporary GitHub problem. Wait a few minutes, then deliver again.
  • Hamster's GitHub App identity could not be resolved. Try again in a moment. A temporary GitHub problem. Wait a moment, then deliver again.

During the Run

  • Branch not found on GitHub: Shows on the Pushing branch card. The agent didn't push its branch, so Hamster opened no pull request. Read the agent's final report in the delivery thread to see what stopped it.
  • Agent ended without producing durable work: no PR/branch and no plan tasks were completed. The agent finished without pushing a branch or completing a task. Read its report, then deliver again.
  • Agent never opened an authenticated MCP session within 300s, so it could not mark tasks done; failing the delivery. The agent didn't reach Hamster MCP, so it couldn't update tasks. Deliver again.
  • Timed out after 6h. A run still going 6 hours after it started fails. A reason follows, such as Provider credentials unavailable. after the team key was removed. Check the session in the OpenAI dashboard, then deliver again.
  • Cloud Agents — Hamster's own cloud agents are separate from OpenAI Agents.
  • Cursor — The same delivery shape on your Cursor account.
  • GitHub — Connect the repositories OpenAI Agents delivers to.
  • Delivering Briefs — Choose a provider when a Brief is ready.
  • Reviewing Briefs — Review the draft pull request the delivery opens.