# Robota — SDK and agent interfaces

> Our agents develop and advance our agents. [VISION.md](VISION.md) owns this direction: building
> a dependable, adaptable foundation for agents to carry their own development forward.
> Reliable autonomous self-evolution is an ambition, not a shipped guarantee.

Today, composable TypeScript libraries provide strict types, multi-provider support and a
plugin/event architecture. The SDK and maintained interfaces form one environment;
`@robota-sdk/agent-cli` delivers a coding-capable terminal agent built from those same libraries.

This file is a map for agent consumers evaluating or embedding the Robota SDK. Facts live in their owner
documents — follow the links; do not infer capabilities from package counts or quickstart defaults.
(`AGENTS.md`/`CLAUDE.md` are contributor-harness docs, not consumer docs.)

## Minimal embedding set

`agent-core` plus one provider package; add `agent-tools` for tools. The other `@robota-sdk/*`
packages are optional assembly on top of them. Published packages need Node.js >= 22.12.

- [packages/agent-core/README.md](packages/agent-core/README.md): `ConversationAgent` class — `run`/`runStream`, conversation history, plugins, structured output
- [content/guide/providers.md](content/guide/providers.md): one provider package per vendor — `agent-provider-anthropic`, `-openai`, `-gemini`, `-openai-compatible` (DeepSeek / Qwen / Gemma), `-bytedance` (video)
- [packages/agent-tools/README.md](packages/agent-tools/README.md): zod-validated function tools + built-in tool factories

## Capabilities

- **OpenAI-compatible gateway via `baseURL`** — any gateway (Vercel AI Gateway, LiteLLM, OpenRouter), Azure, vLLM, Ollama, LM Studio; non-OpenAI model slugs pass through verbatim; streaming + tool calling included. Owner JSDoc: [packages/agent-provider-openai/src/openai/types.ts](packages/agent-provider-openai/src/openai/types.ts); guide: [content/guide/providers.md](content/guide/providers.md)
- **Streaming** — `runStream()` or per-run `onTextDelta`: [content/guide/building-agents.md](content/guide/building-agents.md)
- **Schema-enforced structured output** — `run(prompt, { output: zodSchema })` returns a validated typed object with provider-native mapping + bounded retry: [packages/agent-core/docs/SPEC.md](packages/agent-core/docs/SPEC.md) § Structured Output Contract
- **Runtime tool validation** — zod schemas validate tool args before executors run: [packages/agent-tools/README.md](packages/agent-tools/README.md)
- **Step control** — `maxExecutionRounds` (a round = one model call + its requested tool executions): [content/guide/building-agents.md](content/guide/building-agents.md) § Execution contracts
- **Model fallback** — `FallbackProvider` (`@robota-sdk/agent-framework`) moves a request to the next model of a chain when the primary fails in a way another model could serve, never after text has streamed. Owner JSDoc: [packages/agent-framework/src/routing/fallback-provider.ts](packages/agent-framework/src/routing/fallback-provider.ts); contract: [packages/agent-framework/docs/SPEC.md](packages/agent-framework/docs/SPEC.md) § Guarantees and invariants
- **Sessions, permissions, `createQuery()`** — `InteractiveSession`, permission modes and rules, hooks, config/context loading: [packages/agent-framework/README.md](packages/agent-framework/README.md); [content/guide/permissions-and-hooks.md](content/guide/permissions-and-hooks.md)
- **MCP** — client (`@robota-sdk/agent-mcp`): [packages/agent-mcp/README.md](packages/agent-mcp/README.md); serve a session as an MCP server (`@robota-sdk/agent-transport-mcp`): [packages/agent-transport-mcp/README.md](packages/agent-transport-mcp/README.md)
- **Editors (ACP)** — run a session as an Agent Client Protocol agent for Zed, JetBrains and other ACP clients (`robota acp`, `@robota-sdk/agent-transport-acp`): [packages/agent-transport-acp/README.md](packages/agent-transport-acp/README.md); guide: [content/guide/cli.md](content/guide/cli.md)
- **Real-terminal testing** — the TUI package tests itself in a real PTY; that support is internal, not a published test API: [packages/agent-ui-terminal/docs/SPEC.md](packages/agent-ui-terminal/docs/SPEC.md) § Boundaries

## Behavior contracts

- **Run concurrency** — per-instance FIFO serialization; concurrent `run()` calls never interleave history: [packages/agent-core/docs/SPEC.md](packages/agent-core/docs/SPEC.md) § Run Concurrency Contract
- **History lifetime & cost** — append-only, full history sent every call; `clearHistory()` resets, systemMessage re-applies; `retainHistory: false` = run-isolated (stateless) mode: [content/guide/building-agents.md](content/guide/building-agents.md) § History lifetime and cost
- **`destroy()`** — best-effort: never rejects, safe to fire-and-forget, failures returned as `{ errors }`: [content/guide/building-agents.md](content/guide/building-agents.md) § Execution contracts
- **Tool-only turns** — `allowToolOnlyCompletion: true` makes a tool call a valid completion (decision agents, no summary-call tax): [content/guide/building-agents.md](content/guide/building-agents.md) § Decision agents
- **Unattended permission default** — `createQuery()` runs in the `default` permission mode: with no approver, a call that would ask is denied unless you pass another `permissionMode`: [packages/agent-framework/README.md](packages/agent-framework/README.md)

## Types & examples

- Type declarations ship inside each npm package (`dist/**/*.d.ts`) — the hover docs above are in them. Repo sources: [packages/agent-core/src/index.ts](packages/agent-core/src/index.ts), [packages/agent-provider-openai/src/index.ts](packages/agent-provider-openai/src/index.ts), [packages/agent-tools/src/index.ts](packages/agent-tools/src/index.ts)
- Quickstart: [content/quickstart.md](content/quickstart.md) (includes the AI-gateway path)
- Runnable examples — capabilities ("what can it do"): [examples/capabilities/openai-compatible-gateway](examples/capabilities/openai-compatible-gateway), [examples/capabilities/decision-agent](examples/capabilities/decision-agent), [examples/capabilities/streaming](examples/capabilities/streaming), [examples/capabilities/stateless-turns](examples/capabilities/stateless-turns); integrations ("where does it go"): [examples/express](examples/express), [examples/discord-bot](examples/discord-bot), [examples/batch-processor](examples/batch-processor)
- All packages: [README.md](README.md) § Packages
