graph LR
A["<b style='color:#9370db'>system</b><br/>once, at the start"] --> B["<b style='color:#1aa0fe'>user</b>"] --> C["<b style='color:#007f31'>assistant</b><br/>calls a tool"] --> D["<b style='color:#ff6d2f'>tool</b><br/>the result"] --> E["<b style='color:#007f31'>assistant</b><br/>final answer"]
classDef purple fill:#ececff,stroke:#9370db,color:#3d3163;
  classDef blue fill:#e0f2fe,stroke:#1aa0fe,color:#0c4a6e;
  classDef green fill:#e3fbf1,stroke:#007f31,color:#10704b;
  classDef orange fill:#fff1e6,stroke:#ff6d2f,color:#9a3f12;
  classDef gray fill:#f1f1f1,stroke:#9ca3af,color:#4b5563;
class A purple
class B blue
class C,E green
class D orange
linkStyle 0 stroke:#1aa0fe,stroke-width:2px;
  linkStyle 1 stroke:#007f31,stroke-width:2px;
  linkStyle 2 stroke:#ff6d2f,stroke-width:2px;
  linkStyle 3 stroke:#007f31,stroke-width:2px;

{
  "messages": [
    { "role": "system", "content": "You are a terse coding assistant." },
    { "role": "user", "content": "What does this function do?" },
    { "role": "assistant", "content": "It reverses a linked list in place." },
    { "role": "user", "content": "Now add a docstring." }
  ]
}

{
  "messages": [...],
  "tools": [
    {"type": "agentaus_web_fetch"}
  ],
  ...
}

{
  "type": "function",
  "function": {
    "name": "get_exchange_rate",
    "description": "Get the exchange rate between two currencies",
    "parameters": {
      "type": "object",
      "properties": {
        "from": {"type": "string", "description": "Source currency code"},
        "to": {"type": "string", "description": "Target currency code"}
      },
      "required": ["from", "to"]
    }
  }
}

{
  "messages": [
    { "role": "user", "content": "What's the weather in Sydney, and what's on my calendar today?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City and state" }
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "get_calendar_events",
        "description": "List the user's calendar events for a given date",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "ISO 8601 date, e.g. 2026-09-16" }
          },
          "required": ["date"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "stream": false
}

{
  "messages": [...],
  "tools": [
    {
      "type": "agentaus_dataset_search",
      "dataset_ids": ["5a1f7e2c-...", "9c3d1a44-..."]
    }
  ],
  ...
}

graph TD
T["<b style='color:#1aa0fe'>tools</b><br/>catalog: A, B, C"] --> TC{tool_choice}
TC -->|"<span style='padding:1px 8px; font-weight:bold;'>auto</span>"| AUTO["model may call A, B, or C —<br/>or reply with text"]
TC -->|"<span style='padding:1px 8px; font-weight:bold;'>required</span>"| REQ["model must call<br/>one of A, B, C"]
TC -->|"<span style='padding:1px 8px; font-weight:bold;'>none</span>"| NONE["model must reply<br/>with text"]
TC -->|"<span style='padding:1px 8px; font-weight:bold;'>allowed_tools<br/>{A, B}</span>"| SUB["<b style='color:#9370db'>narrowed to A, B</b><br/>(tools ∩ allowlist)"]
SUB -->|"<span style='padding:1px 8px; font-weight:bold;'>mode: auto</span>"| SUBAUTO["may call A or B —<br/>or reply with text"]
SUB -->|"<span style='padding:1px 8px; font-weight:bold;'>mode: required</span>"| SUBREQ["must call A or B"]
classDef purple fill:#ececff,stroke:#9370db,color:#3d3163;
  classDef blue fill:#e0f2fe,stroke:#1aa0fe,color:#0c4a6e;
  classDef green fill:#e3fbf1,stroke:#007f31,color:#10704b;
  classDef orange fill:#fff1e6,stroke:#ff6d2f,color:#9a3f12;
  classDef gray fill:#f1f1f1,stroke:#9ca3af,color:#4b5563;
class T,TC blue
class AUTO,SUBAUTO green
class REQ,SUBREQ orange
class NONE gray
class SUB purple
linkStyle 0 stroke:#9370db,stroke-width:2px;
  linkStyle 1 stroke:#007f31,stroke-width:2px;
  linkStyle 2 stroke:#ff6d2f,stroke-width:2px;
  linkStyle 3 stroke:#9ca3af,stroke-width:2px;
  linkStyle 4 stroke:#9370db,stroke-width:2px;
  linkStyle 5 stroke:#007f31,stroke-width:2px;
  linkStyle 6 stroke:#ff6d2f,stroke-width:2px;

{
  "messages": [{"role": "user", "content": "Sydney"}],
  "tools": [ /* get_current_weather, as above */ ],
  "tool_choice": "required",
  "stream": false
}

{
  "messages": [
    {"role": "user", "content": "Never mind the live lookup — just tell me in general terms what Sydney's weather is like in September."}
  ],
  "tools": [ /* get_current_weather, as above */ ],
  "tool_choice": "none",
  "stream": false
}

{
  "messages": [
    {"role": "user", "content": "What's the weather in Sydney, and what's on my calendar today?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": { "name": "get_current_weather", "description": "...", "parameters": {} }
    },
    {
      "type": "function",
      "function": { "name": "get_calendar_events", "description": "...", "parameters": {} }
    },
    {
      "type": "function",
      "function": { "name": "send_email", "description": "...", "parameters": {} }
    }
  ],
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "required",
    "tools": [
      {"type": "function", "name": "get_current_weather"},
      {"type": "function", "name": "get_calendar_events"}
    ]
  },
  "stream": false
}

graph LR
R["Request"] -->|"<span style='padding:1px 8px; font-weight:bold;'>stream: false</span>"| J["<b style='color:#007f31'>Single JSON object</b><br/>200 OK, all at once"]
R -->|"<span style='padding:1px 8px; font-weight:bold;'>stream: true (default)</span>"| S["<b style='color:#1aa0fe'>SSE chunks</b><br/>tokens/deltas as they're generated"] --> D["data: [DONE]"]
classDef purple fill:#ececff,stroke:#9370db,color:#3d3163;
  classDef blue fill:#e0f2fe,stroke:#1aa0fe,color:#0c4a6e;
  classDef green fill:#e3fbf1,stroke:#007f31,color:#10704b;
  classDef orange fill:#fff1e6,stroke:#ff6d2f,color:#9a3f12;
  classDef gray fill:#f1f1f1,stroke:#9ca3af,color:#4b5563;
class R purple
class J green
class S blue
class D gray
linkStyle 0 stroke:#007f31,stroke-width:2px;
  linkStyle 1 stroke:#1aa0fe,stroke-width:2px;

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "Hello! How can I assist you today?",
        "refusal": null,
        "role": "assistant",
        "tool_calls": []
      }
    }
  ],
  "created": 1781059264,
  "id": "chatcmpl-1781059264",
  "model": "agentaus",
  "object": "chat.completion",
  "usage": {
    "input_tokens": 2440,
    "output_tokens": 70
  }
}

data: {"id":"resp_42","object":"chat.completion.chunk","created":1757930000,"model":"agentaus","choices":[{"text":"A ","index":0,"delta":{"role":"assistant","content":"A "},"finish_reason":null}]}

data: {"id":"resp_42","object":"chat.completion.chunk","created":1757930001,"model":"agentaus","choices":[{"text":"function ","index":0,"delta":{"role":"assistant","content":"function "},"finish_reason":null}]}

... (more chunks) ...

data: {"id":"resp_42","object":"chat.completion.chunk","created":1757930005,"model":"agentaus","choices":[{"delta":{},"finish_reason":"stop","index":0}],"usage":null}

data: {"id":"resp_42","object":"chat.completion.chunk","created":1757930005,"model":"agentaus","choices":[],"usage":{"input_tokens":14,"output_tokens":21}}

data: [DONE]

data: {"id":"resp_42","object":"chat.completion.chunk","created":1757930000,"model":"agentaus","choices":[{"index":0,"delta":{"role":"assistant","tool_calls":[{"index":0,"id":"call_abc123","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\": \"Sydney, NSW\"}"}}]},"finish_reason":"tool_calls"}]}

data: [DONE]

data: {"error": {"message": "..."}}

data: [DONE]

{
  "status": 400,
  "message": "The request cannot be fulfilled",
  "data": { "messages": ["is required"] }
}