AI-Assisted Integration

These docs now serve two workflows at once: people reading the docs themselves, and people preparing the right context so an AI coding tool can implement the integration directly.

If you are using Claude, Codex, Cursor, ChatGPT, or a similar tool, this is the recommended reading flow.

Recommended workflow

1. Start with Choose Your Stack and decide whether your path is modelkit, agentkit, or ragkit
2. Open the relevant quickstart and copy both the recommended prompt and the minimal fact checklist into your AI tool
3. Ask the AI to make the change in your real project, not just explain the approach
4. Use the manual verification checklist from the docs to confirm the AI did not get key AgentOS facts wrong
5. If the generated code drifts, return to the examples as reference truth

What to give the AI

Provide these five inputs together when possible:

• Project type: Node.js, TypeScript, Dart, Flutter
• Current state: greenfield, existing OpenAI integration, existing custom agent, existing knowledge base
• Target capability: LLM, TTS, ASR, embeddings, agent, RAG
• Expected output: complete code, incremental refactor, minimal diff, debugging checklist
• AgentOS constraints: where baseURL, apiKey, and model must come from

General prompt template

Replace the placeholders below and send the result to your AI coding tool:

You are my pair engineer. Implement the AgentOS integration directly in the project instead of only describing the approach.

Project context:
- Project type: [Node.js / TypeScript / Dart / Flutter]
- Current state: [greenfield / existing OpenAI integration / existing custom agent / existing knowledge base]
- Capability I want: [modelkit / agentkit / ragkit / tts / asr / embeddings]
- Output I want: [complete runnable code / adapt existing code / minimal diff / troubleshooting fix]

AgentOS facts you must follow:
- If this uses the official OpenAI SDK directly, chat baseURL is `${baseUrl}/modelkit/chat/v1`, where `baseUrl` comes from the AgentOS root endpoint
- apiKey comes from the bearer token returned by registerBundle or POST /appkit/register
- model comes from `sdk.modelkit.listModelsByTask(ModelTask.chat)`, or a `task=chat` `model.id` from `GET /modelkit/models`
- Do not invent AgentOS APIs, field names, or initialization flows
- If the docs provide a minimal example, stay close to that structure

Work in this order:
1. First decide whether this scenario fits modelkit, agentkit, or ragkit, and explain why
2. Then modify the code based on that decision
3. List the environment variables, dependencies, and run commands I need
4. Give me a manual verification checklist for confirming the integration works
5. Ask follow-up questions only if something is truly blocking implementation

Minimal AgentOS fact checklist

These are the highest-value facts to send along with the prompt:

Fact	Correct source
Gateway address	Your deployed AgentOS URL, for example http://127.0.0.1:8888
OpenAI SDK baseURL	For chat, ${baseUrl}/modelkit/chat/v1, where baseUrl comes from the AgentOS root endpoint
OpenAI SDK apiKey	Bearer token from registerBundle or POST /appkit/register
OpenAI SDK model	A model.id for the corresponding ModelKit task
If the app already has a complex agent	Usually prefer modelkit, not agentkit
If you have tools but do not want to orchestrate the agent yourself	Usually prefer agentkit
If you need document workflows and knowledge retrieval	Usually prefer ragkit

Manual verification checklist

After the AI writes code, manually confirm at least these points:

• It really calls registerBundle or explicitly uses an existing bearer token
• It points baseURL to AgentOS baseUrl, not the default OpenAI endpoint
• It selects a model from listModels() or another known valid model, not a made-up id
• It distinguishes between "I already have my own agent" and "I want AgentKit to orchestrate tools and sessions"
• It treats the minimal example as reference structure instead of inventing a new SDK initialization flow

Where to go next

• Not sure which path fits: Choose Your Stack
• Integrating TypeScript first: TypeScript Quickstart
• Need a minimal reference implementation: TypeScript Minimal App