Agent Registration API

Fastest Way to Create an Agent

The easiest path is to log in to Ozwell Manager with MIE auth (manager.os.mieweb.org credentials) and create/manage agents in the manager UI.

Ozwell Manager uses the container console login. After login, Ozwell reads trusted forwarded identity headers, provisions or links your ozw_ parent key, and creates agent keys for your agents.

Getting an API Key

For managed Ozwell, first-time users get an ozw_ parent key automatically after logging in to Ozwell Manager. Existing users can claim an existing ozw_ key there.

Agents let you define persona, temperature, tools, and model policy server-side. Clients authenticate with a lightweight agent key (agnt_key-) instead of a full API key — keeping your configuration secure and your embed code simple.

See Authentication for the parent-key and agent-key lifecycle.

Agent chat requests are processed by whichever backend the server has configured (LLM gateway, Ollama, or mock). See the reference server README for backend configuration details.

Base URLs

Environment	URL
Current Ozwell Manager API	https://ozwellapi.os.mieweb.org

Use the current Ozwell Manager API for the full manager-console experience. Production is temporarily unavailable while it migrates to the future api.ozwell.ai endpoint, so it is not advertised as the active API here.

Authentication

Ozwell Manager uses trusted forwarded identity headers from the manager console/proxy. Users do not paste a parent key into the manager UI.

The lower-level agent management API still supports parent API key auth (ozw_ prefix) in the Authorization header:

Authorization: Bearer ozw_your_api_key_here

Quick Start

Option A — Create an agent in the UI

1. Log in to Ozwell Manager with MIE auth (manager.os.mieweb.org credentials).
2. Ozwell automatically provisions your ozw_ parent key if you do not already have one.
3. Create or edit your agent in the manager page.
4. Copy the returned agent_key and use it in your widget embed.
5. Use Claim key only if you need to attach an existing ozw_ parent key and migrate older agents.

Option B — Create an agent via API

If you want the lower-level/manual flow, use the API directly:

Step 1 — Set your server and key

BASE="https://ozwellapi.os.mieweb.org"
AUTH="Authorization: Bearer ozw_your_api_key_here"

Step 2 — Create an agent

Send raw YAML directly with Content-Type: application/yaml:

curl -s -X POST "$BASE/v1/agents" \
  -H "$AUTH" \
  -H "Content-Type: application/yaml" \
  -d '
name: My Agent
instructions: You are a helpful assistant.
model: llama3.1:latest
temperature: 0.7
' | jq .

Or from a file:

curl -s -X POST "$BASE/v1/agents" \
  -H "$AUTH" \
  -H "Content-Type: application/yaml" \
  -d @my-agent.yaml | jq .

Alternative: JSON-wrapped YAML

curl -s -X POST "$BASE/v1/agents" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"yaml": "name: My Agent\ninstructions: You are a helpful assistant.\nmodel: llama3.1:latest\ntemperature: 0.7\n"}' | jq .

Step 3 — Grab the agent_key from the response

{
  "agent_id": "agent-mmefp8bk...",
  "agent_key": "agnt_key-mmefp8bk...",
  "parent_key": "demo-key",
  "created_at": 1772773719
}

Step 4 — Use the agent key in your embed

<script>
  window.OzwellChatConfig = { apiKey: 'agnt_key-abc123...' };
</script>
<script src="https://ozwellapi.os.mieweb.org/widget"></script>

That's it — 4 steps: set credentials, create agent, copy the key, embed it.

---

Key Types

Key Type	Prefix	Purpose	Who uses it
API Key	ozw_	Manage agents (create, update, delete)	Developers / admins
Agent Key	agnt_key-	Authenticate chat requests for a specific agent	End-user widgets / embeds

Agent keys are generated automatically when you create an agent. They are scoped to that agent's behavior, tools, and model policy.

---

Endpoints

Create Agent

POST /v1/agents

Create a new agent with a YAML configuration wrapped in JSON.

Request Body

{
  "yaml": "name: My Agent\ninstructions: You are a helpful assistant.\nmodel: llama3.1:latest\ntemperature: 0.7\ntools:\n  - name: get_form_data\n    description: Retrieves form values\n  - name: search_docs\n    description: Searches documentation\n    inputSchema:\n      type: object\n      properties:\n        query:\n          type: string\n"
}

YAML Fields

Field	Type	Required	Description
name	string	Yes	Display name for the agent
instructions	string	Yes	System prompt / persona. Must describe when and how to use each tool — the LLM relies on instructions (not tool descriptions) to decide which tool to call.
model	string	No	Legacy model default. New provider/model defaults and restrictions live in the manager model-policy APIs, not in behavior YAML.
temperature	number	No	Sampling temperature 0-2 (default: 0.7)
tools	array	No	Server-side tool definitions. Each entry can be a name string or an object with name, description, and inputSchema fields. These are always available to the agent. Page-provided tools are separate and controlled by pageTools.
pageTools	string or object	No	Controls which page-provided tools (via postMessage_ prefix) the agent can call. all (default) — accept everything. { restricted: [...] } — only these page tools. { blocked: [...] } — all page tools except these.
behavior	object	No	Optional tone and rules (e.g., tone, rules array)

Provider/model policy is stored separately from YAML so agent behavior remains provider-agnostic. Existing YAML with model still works as legacy fallback, but new saves should use GET/PUT /v1/manager/agents/{agent_id}/model-policy for fallback provider/model and allowed-model restrictions.

An agent policy narrows what is already allowed above it; it can never widen it. The full order is:

discovered models → server-wide policy → parent-key policy → agent policy

So an agent can only select models that the owning parent key allows, and the parent key can only allow models the server-wide policy permits. If an admin narrows the server-wide policy, an agent policy naming an excluded model stays saved but stops resolving, and chat requests for that model are rejected with 403 model_not_allowed before any provider is called. See API Endpoints for the server-wide and parent-key endpoints.

That order decides which models are allowed. Which one is picked when a request names none is a separate chain, and the agent default still comes first:

agent model-policy default → server-wide fallback → environment → gpt-4o-mini

An agent with no default model therefore falls through to whatever an admin set through PUT /v1/manager/admin/default-model, and only then to the environment. The environment step depends on the backend in use: LLM_MODEL when LLM_BASE_URL is set, the first Ollama model when it is not and Ollama is reachable, otherwise DEFAULT_MODEL.

Example

curl -s -X POST "$BASE/v1/agents" \
  -H "$AUTH" \
  -H "Content-Type: application/yaml" \
  -d '
name: Support Bot
model: llama3.1:latest
temperature: 0.5
tools:
  - name: search_docs
    description: Search the knowledge base for relevant articles
    inputSchema:
      type: object
      properties:
        query:
          type: string
          description: Search query
      required:
        - query
  - name: create_ticket
    description: Create a support ticket to escalate an unresolved issue
    inputSchema:
      type: object
      properties:
        subject:
          type: string
          description: Ticket subject
        description:
          type: string
          description: Detailed issue description
      required:
        - subject
instructions: >
  You help users with technical support. Be concise and friendly.
  When a user asks a question, call search_docs to find relevant articles.
  If the issue cannot be resolved, call create_ticket to escalate it.
' | jq .

Note: Tool schemas (description + inputSchema) are stored server-side with the agent. The LLM receives these schemas automatically — no client-side tool configuration needed.

Response

{
  "agent_id": "agent-mmefp8bk...",
  "agent_key": "agnt_key-mmefp8bk...",
  "parent_key": "demo-key",
  "created_at": 1772773719
}

---

List Agents

GET /v1/agents

Returns all agents associated with your API key.

Example

curl -s "$BASE/v1/agents" -H "$AUTH" | jq .

Response

{
  "object": "list",
  "data": [
    {
      "id": "agent-abc123...",
      "agent_key": "agnt_key-abc123...",
      "name": "Support Bot",
      "model": "llama3.1:latest",
      "tools": [{"name": "search_docs", "description": "Searches documentation"}],
      "behavior": {
        "tone": "friendly and helpful",
        "rules": ["Always be helpful"]
      },
      "markdown": "---\nname: Support Bot\nmodel: llama3.1:latest\n...",
      "created_at": 1772685931
    }
  ]
}

Note: The behavior field only appears if defined in the agent's YAML. tools defaults to [] if not specified.

---

Get Agent

GET /v1/agents/{agent_id}

Retrieve full details for a single agent, including parsed definition and instructions.

Example

curl -s "$BASE/v1/agents/agent-mmefp8bk" -H "$AUTH" | jq .

Response

{
  "agent_id": "agent-mmefp8bk...",
  "parent_key": "demo-key",
  "created_at": 1772773719,
  "markdown": "---\nname: Support Bot\nmodel: llama3.1:latest\ntemperature: 0.5\ntools:\n  - search_docs\n---\n\nYou help users with technical support.",
  "definition": {
    "name": "Support Bot",
    "model": "llama3.1:latest",
    "temperature": 0.5,
    "tools": [{"name": "search_docs", "description": "Searches documentation"}]
  },
  "instructions": "You help users with technical support."
}

---

Update Agent

PUT /v1/agents/{agent_id}

Update an existing agent's configuration. Same YAML-in-JSON format as create.

Example

curl -s -X PUT "$BASE/v1/agents/agent-mmefp8bk" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"yaml": "name: Support Bot v2\ninstructions: You are an updated support bot.\nmodel: llama3.1:latest\ntemperature: 0.3\n"}' | jq .

Response

{
  "agent_id": "agent-mmefp8bk...",
  "agent_key": "agnt_key-mmefp8bk...",
  "parent_key": "demo-key",
  "name": "Support Bot v2",
  "model": "llama3.1:latest",
  "tools": [{"name": "search_docs", "description": "Searches documentation"}],
  "updated": true
}

---

Delete Agent

DELETE /v1/agents/{agent_id}

Permanently delete an agent and invalidate its agent key.

Example

curl -s -X DELETE "$BASE/v1/agents/agent-mmefp8bk" -H "$AUTH" | jq .

Response

{
  "id": "agent-mmefp8bk...",
  "deleted": true
}

---

Error Responses

Status	Meaning
400	Bad request — invalid YAML, missing fields, or invalid API key
401	Unauthorized — missing or invalid Authorization header
404	Agent not found

{
  "error": "Agent not found"
}

---

See Also

• Authentication — API key types and security
• CDN Embed — Using agent keys in the embed widget
• API Endpoints — Full endpoint reference