Usage for Agents

Not yet available. The Agent SDK is tracked to be built — today, use the Client SDKs against the live chat completions API. The guidance below describes intended patterns.

The Agent SDK is designed for loops, not one-off calls. These patterns apply whether you're building a simple Q&A bot or a multi-step orchestrator with tool calls and approval gates.

Structure your agent around items#

The SDK's item list is append-only — never mutate past turns. Each call to callModel() returns a new list of items that extends the previous list. Pass the returned list as input to the next turn.

let items = [];

const result = await client.callModel({
  model: "google/gemini-2.5-pro",
  messages: [{ role: "user", content: goal }],
  inputItems: items,
  tools: [searchTool, calculatorTool],
  stopConditions: [{ type: "no_tool_calls" }],
});

items = result.items;

Declare stop conditions explicitly#

Rather than breaking out of a loop manually, declare the conditions under which the agent is done. This makes the loop body smaller and the behavior auditable.

Common stop conditions:

• no_tool_calls — model responded without calling any tool (task is complete).
• max_turns: N — hard cap on iterations.
• balance_below: N — halt before running out of DA balance.
• output_schema — stop when the output matches a declared JSON schema.

Register tools once#

Define your tools at startup and pass the registry to every callModel() call. The SDK handles invocation, error capture, and result injection automatically.

const tools = client.tools([
  {
    name: "get_weather",
    description: "Get current weather for a city.",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string" },
      },
      required: ["city"],
    },
    execute: async ({ city }) => fetchWeather(city),
  },
]);

Handle approval gates for sensitive tools#

Some tools — sending an email, writing to a database, making a payment — should pause for human review before executing. The SDK supports a per-tool approval hook that lets you intercept, inspect, and approve or reject each invocation before it runs. See Tool Approval & State Persistence.

Stream output for long-running turns#

Use streaming when a turn might produce long text. The SDK reassembles delta chunks and delivers tool-call results in the same stream. See Streaming.

Monitor balance across turns#

The SDK exposes the X-Balance-Available header after each turn. Use a balance_below stop condition to halt gracefully before the balance hits zero — a mid-loop 402 error is harder to recover from than a clean stop.

Use dynamic parameters for adaptive loops#

If you need to adjust temperature, max_tokens, or model mid-loop based on what happened in prior turns, use dynamic parameters — functions that receive the current item list and return updated call parameters. See Dynamic Parameters.

Also see#

• Call Model — full callModel() reference.
• Stop Conditions — declarative loop termination.
• Tools — tool registration and dispatch.
• Example: Weather Tool — end-to-end example.