> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Ground one TypeScript SDK workflow with managed web search

> Use the official TypeScript SDK with presets, managed web search, and response metadata so one workflow stays grounded and debuggable.

Use this recipe when a TypeScript or JavaScript service should combine:

* preset-driven routing defaults
* managed `phaseo:web_search`
* strict response parsing
* request-level metadata for debugging

## Goal

* keep the caller on the official SDK
* avoid rebuilding raw compatibility payloads by hand
* preserve enough metadata to debug search results, routing, and plugin behavior

## 1. Start with one shared client

```ts theme={null}
import Phaseo from "@phaseo/sdk";

export const gateway = new Phaseo({
  apiKey: process.env.PHASEO_API_KEY!,
});
```

## 2. Put stable defaults in a preset first

Create a preset when multiple callers should share:

* model policy
* provider preferences
* reasoning defaults
* system prompt
* deterministic caching behavior

Then keep the SDK request focused on what varies for the one call.

## 3. Ask for grounded output through the managed search tool

```ts theme={null}
const response = await gateway.generateResponse({
  preset: "research-brief",
  input: "Find the latest public changes to our webhook delivery behavior and summarize them.",
  tools: [
    {
      type: "phaseo:web_search",
      parameters: {
        query: "site:phaseo.app webhook delivery retries",
        max_results: 5,
        include_highlights: true,
      },
    },
  ],
  tool_choice: "phaseo:web_search",
  response_format: {
    type: "json_schema",
    name: "research_brief",
    schema: {
      type: "object",
      required: ["summary", "sources"],
      properties: {
        summary: { type: "string" },
        sources: {
          type: "array",
          minItems: 1,
          items: {
            type: "object",
            required: ["title", "url"],
            properties: {
              title: { type: "string" },
              url: { type: "string", format: "uri" },
            },
            additionalProperties: false,
          },
        },
      },
      additionalProperties: false,
    },
  },
  plugins: [{ id: "response-healing" }],
  meta: true,
});
```

This gives you:

* preset-managed routing and prompt defaults
* server-managed search that works without depending on provider-native search support
* structured output for predictable downstream parsing
* metadata needed for operational debugging

## 4. Parse the output and keep the debug fields

```ts theme={null}
const firstMessage = Array.isArray(response.output)
  ? response.output.find((item) => item?.type === "message")
  : null;

const text = Array.isArray(firstMessage?.content)
  ? firstMessage.content.find((part) => part?.type === "output_text")?.text ?? ""
  : "";

const payload = JSON.parse(text);

console.log({
  responseId: response.id,
  selectedProvider: response.meta?.routing?.selected_provider,
  pluginExecutions: response.meta?.plugin_executions,
  serverToolUse: response.usage?.server_tool_use,
});

console.log(payload);
```

These fields make it much easier to answer:

* which provider actually served the request
* whether managed search ran
* whether response healing ran
* which request to inspect in the dashboard

## 5. Verify the grounded request in logs

Open the request in **Gateway -> Usage** and inspect:

* normalized search results
* citations
* provider selection
* plugin execution metadata

If the search behavior or ranking looks wrong, fix the preset or tool parameters from evidence in logs rather than adding blind overrides.

## 6. Split exploratory and deterministic workflows

Recommended pattern:

1. one preset for deterministic structured research outputs
2. another preset for exploratory or higher-temperature requests

That keeps:

* response caching cleaner
* routing behavior easier to reason about
* search-heavy workflows separate from general-purpose generation traffic

## Related

* [Debug web search requests](https://phaseo.app/docs/v1/cookbook/web-search-debugging.md)
* [Roll out presets and debug routing](https://phaseo.app/docs/v1/cookbook/preset-rollout-and-routing-debug.md)
* [Use response healing for structured JSON](https://phaseo.app/docs/v1/cookbook/response-healing-for-structured-json.md)
* [TypeScript SDK Overview](https://phaseo.app/docs/v1/sdk-reference/typescript/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.