mobius

Get started free
Get started free

API

Agent definitions

The agent definition API lets a product backend supply instructions, model settings, toolkits, and skills without copying that behavior into every Mobius tenant.

Use inline config when your backend initiates the turn. Use a definition resolver when Mobius initiates work from a schedule or trigger.

Send an inline definition

Add config to an agent invocation:

{
  "agent_ref": { "id": "<agent-id>" },
  "session": {
    "mode": "continue_or_create",
    "session_key": "app:<account-id>:support"
  },
  "config": {
    "instructions": "Answer support questions and cite ticket numbers.",
    "model": "claude-sonnet-4-6",
    "effort": "medium",
    "timeout_seconds": 120,
    "toolkits": [
      { "name": "tickets", "actions": ["tickets.search", "tickets.get"] }
    ],
    "skills": [
      {
        "name": "refunds",
        "description": "Rules for issuing a refund",
        "body": "<skill-instructions>"
      }
    ]
  },
  "input": {
    "content": [{ "type": "text", "text": "Summarize my open tickets." }],
    "idempotency_key": "<message-id>"
  }
}

The resolved session stores this config:

  • Sending config on session creation establishes the session definition.
  • Sending it on a later turn replaces the saved definition.
  • Omitting it keeps the current definition.
  • Sending {} clears it and returns to the agent's stored definition.

Supplied toolkit names can select only actions already available in the project catalog. Organization limits still cap timeout and model access. An inline definition can narrow behavior, but it cannot grant new access.

Configure a definition resolver

An organization owner or admin replaces the resolver configuration at:

PUT /v1/organization/definition-resolver
{
  "source": "client_resolver",
  "endpoint_url": "https://api.example.com/mobius/resolve",
  "auth": {
    "mode": "bearer",
    "token": "<shared-secret>"
  },
  "timeout_ms": 2000,
  "revalidate_after_s": 30,
  "stale_max_age_s": 3600,
  "on_unavailable": "last_known_good"
}

The PUT is a full replacement. Omitted configurable fields return to their defaults. Omitting auth is the exception: Mobius keeps the sealed token so a routine policy edit does not require the secret again.

Read the current redacted configuration with GET on the same path. auth_configured, last_good_digest, and last_good_at reveal whether a token and a cached definition exist without returning either secret.

Implement the resolver endpoint

At run start, Mobius sends a batch request with the project identity, trigger, and requested agent selectors:

{
  "protocol_version": 1,
  "org_id": "<org-id>",
  "project": {
    "id": "<project-id>",
    "external_ref": "<your-workspace-id>"
  },
  "trigger": { "kind": "schedule" },
  "refs": [
    {
      "selector": "agent/scout",
      "known_digest": "sha256:<current-digest>"
    }
  ]
}

Return a definition and a digest:

{
  "resolved": {
    "agent/scout": {
      "digest": "sha256:<new-digest>",
      "value": {
        "agent": {
          "instructions": "Review the pull request.",
          "model": "claude-opus-4-8",
          "effort": "high",
          "timeout_seconds": 600
        },
        "toolkits": [
          { "name": "github", "actions": ["github.pull_request.create_review"] }
        ],
        "skills": []
      }
    }
  }
}

Return { "unchanged": true } when known_digest is still current. Return a per-reference error such as unknown_agent to fail clearly instead of running an empty definition.

Use project.external_ref, not the bearer token, to map the request to your tenant. The token proves the caller is Mobius; the external reference names the tenant in your system.

Availability policy

last_known_good serves the most recent durable definition while the resolver is unavailable, bounded by stale_max_age_s. fail stops the run before it starts. Mobius never silently substitutes an empty definition.

Resolver URLs must use HTTPS. Mobius rejects loopback, link-local, private, and reserved targets and does not follow redirects.

Next