mobius

Get started free
Get started free

Develop

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 reveals whether a token exists without returning it. Resolver results are cached separately for each project and agent, so the org-level response does not report one aggregate last-good digest or timestamp. The optional last_good_digest and last_good_at response properties remain deprecated for SDK compatibility and are not populated.

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