mobius

Get started free
Get started free

Develop

Provision agents

Use external_ref plus if_exists: "adopt" when your product provisions one or more Mobius agents for each of your tenants. The same request can run during signup, retry after a timeout, or run again during reconciliation without creating duplicate agents.

Create or adopt an agent

Choose a durable identifier from your system. Do not use a display name that a customer can change.

POST /v1/agents
Authorization: Bearer <api-key>
Content-Type: application/json
 
{
  "name": "Scout",
  "description": "Acme's support agent",
  "external_ref": "workspace_789:primary-support-agent",
  "if_exists": "adopt"
}

Mobius returns 201 Created for a new agent or 200 OK for the live agent that already owns that external reference. Adoption does not update mutable agent fields, because no write happens. Update the returned agent explicitly when its name, model, instructions, tools, or other configuration should change.

Store the returned id. A deleted agent still owns its external_ref and returns 409. That prevents a later agent from silently assuming the deleted agent's durable identity, sessions, or audit meaning.

Find an agent you already have

If you did not keep the Mobius id, resolve the agent by its exact name or its backing principal instead of guessing:

GET /v1/agents?name=Scout
Authorization: Bearer <api-key>

Follow next_cursor while has_more is true when you enumerate agents.

Identity rules

  • external_ref is unique within the organization.
  • Treat it as assign-once. You may add it to an agent that does not have one, or repeat the same value, but you cannot change an existing value.
  • if_exists: "adopt" requires external_ref. Without it, the request returns 400 because Mobius has no durable identity to match.
  • The default if_exists: "error" keeps the ordinary create contract and returns 409 for a duplicate name or external reference.
  • Use external_ref to reconcile an agent across systems while allowing its display name to change.

Reconcile after ambiguous failures

If your client times out before receiving the response, repeat the same adopt request. A 200 or 201 response is success. Treat conflicts as state that needs operator attention rather than generating a new external reference.

The response is the source of truth. Do not assume the request's mutable fields were applied when the status is 200.

Next