> For the complete documentation index, see [llms.txt](https://docs.frayme.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frayme.ai/agent-frameworks/openai-agents.md).

# OpenAI Agents SDK

Register Frayme's compose tool on an OpenAI Agents SDK (JS) agent — the one shared definition, mapped onto the `parameters` field.

## The one tool definition

`@frayme/api/tools` exports a framework-neutral definition whose schema is Zod v4 (Standard Schema). The Agents SDK's `tool()` accepts it as `parameters`.

```bash
npm i @frayme/api @frayme/runtime @openai/agents
```

```ts
// src/tools/frayme.ts
import { tool } from '@openai/agents';
import Frayme from '@frayme/api';
import { composeToolDefinition, createComposeTool } from '@frayme/api/tools';

const frayme = new Frayme({ apiKey: process.env.FRAYME_API_KEY });
const compose = createComposeTool(frayme);

export const fraymeCompose = tool({
  name: compose.name, // 'frayme_compose'
  description: compose.description,
  parameters: composeToolDefinition.inputSchema,
  // The compose schema uses open JSON maps (`data`, action `params`), which
  // strict structured outputs cannot express — register non-strict.
  strict: false,
  execute: async (input) => {
    const result = await compose.execute(input as Parameters<typeof compose.execute>[0]);

    // Deliver the spec to your front-end out-of-band; return only the
    // correlation handle to the model.
    await deliverSpecToClient(result.spec, result.generation_id);
    return { generation_id: result.generation_id, model: result.model, rendered: true };
  },
});
```

The definition carries the full compose contract — `prompt`, `data`, `actions`, `ui_type`, the 8-verb interaction vocabulary, and three worked call examples — inside `description` and the schema. Nothing to prompt-engineer on your side.

## A minimal agent

```ts
// src/agent.ts
import { Agent, run } from '@openai/agents';
import { fraymeCompose } from './tools/frayme';

const uiAgent = new Agent({
  name: 'UI agent',
  instructions:
    'When an interface serves the user better than prose, call frayme_compose. ' +
    'Pass every fact the UI must show in `data`. Never print the spec as text.',
  tools: [fraymeCompose],
});

const result = await run(
  uiAgent,
  'A refund approval card for order #4821: amount, reason, approve/deny.',
);
```

## Rendering the returned spec

On the client, render the spec your delivery channel hands you:

```tsx
'use client';
import { FraymeRenderer } from '@frayme/runtime/react';
import '@frayme/runtime/styles.css';

<FraymeRenderer
  spec={spec}
  skipValidation // the API already validated before billing
  onDynamicAction={(e) => {
    // { action, event, params, state, generation_id } — a declared action fired.
  }}
/>;
```

Local behaviors — sorting, filtering, tabs, typing over data you supplied — resolve in the browser. Only the actions declared in the compose call reach `onDynamicAction`.

## Closing the loop

Register the round-trip tool so a user interaction recomposes the UI in context:

```ts
import { actionToolDefinition, createActionTool } from '@frayme/api/tools';

const action = createActionTool(frayme);

export const fraymeAction = tool({
  name: action.name, // 'frayme_action'
  description: action.description,
  parameters: actionToolDefinition.inputSchema,
  strict: false,
  execute: async (input) => {
    const result = await action.execute(input as Parameters<typeof action.execute>[0]);
    await deliverSpecToClient(result.spec, result.generation_id);
    return { generation_id: result.generation_id, rendered: true };
  },
});
```

Forward the `onDynamicAction` event to your agent verbatim — `{ action, event, params, state, generation_id }`. The agent calls `frayme_action` with those fields and receives a new validated spec preserving the state the user already entered.

## Next steps

* [@frayme/api reference](/sdk-reference/api.md) — client options, streaming, typed errors
* [@frayme/runtime reference](/sdk-reference/runtime.md) — full renderer props
* [Vercel AI SDK](/agent-frameworks/ai-sdk.md) — if your front-end runs `useChat`, the data-parts bridge streams specs live


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.frayme.ai/agent-frameworks/openai-agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.