# Envai Teams documentation Envai Teams is an HTTP and Server-Sent Events (SSE) API for configuring and running coordinated teams of large language model agents over Agent Team Protocol v3 (ATP v3). A single service origin exposes two runtime planes: - The control plane (`apps/control-plane/`, Laravel 13 on PHP 8.5) manages API keys, JWKS publication (`/.well-known/jwks.json`), the model catalog (`GET /api/v1/models`), and CRUD resources for agent definitions, teams, workspaces, chats, client tools, workspace files, wiki sources, and images. - The execution plane (`apps/execution-plane/`, Go 1.26 gateway) validates Bearer JWTs, loads the team bound to a chat, coordinates the orchestrator and subagent loops, and streams ATP v3 events (`GET /api/v1/atp/v3/chats/{chat_id}/events`). Streaming bytes never pass through PHP. ## Choose how you want to start Pick the path that matches your role. Both entry guides prepare `BASE_URL` and `ENVAI_API_KEY` in your shell and lead into the same [First agent team](getting-started/first-agent-team.md) tutorial: - Use an Envai-hosted service without installing the server: start at [Hosted quickstart](getting-started/hosted.md) to set your service origin and API key using only Bash, `curl`, and `jq`, then continue to [First agent team](getting-started/first-agent-team.md). - Operate your own server: start at [Self-hosted overview](getting-started/self-hosted.md) to choose between a local workstation stack ([Local installation](getting-started/installation.md)) and a non-local deployment ([Deployment](self-hosting/deployment.md)), issue an API key, synchronize the model catalog, and continue to [First agent team](getting-started/first-agent-team.md). ## Getting started - [Hosted quickstart](getting-started/hosted.md) prepares your shell to call an existing Envai-hosted deployment without cloning the repository or running containers. - [Self-hosted overview](getting-started/self-hosted.md) explains operator responsibilities, compares local evaluation with non-local deployment, and connects your server to the shared tutorial. - [Local installation](getting-started/installation.md) brings up the full local development stack (`APP_ENV=local`) on Linux or macOS with Podman or Docker Compose. - [First agent team](getting-started/first-agent-team.md) walks through selecting a tool-capable model, creating a subagent and primary orchestrator, assembling a team, opening a workspace and chat, and streaming a delegated turn over ATP v3. ## Core concepts - [Architecture](concepts/architecture.md) explains the control-plane and execution-plane split, path routing under `/api/v1`, and which internal components matter only to self-hosting operators. - [Agents and teams](concepts/agents-and-teams.md) covers user ownership, `primary` and `subagent` modes, `delegate_task` resolution by agent `name` versus member `role`, model fallback cascades, tool permission rules, and multiplexed stream visibility. - [Chats and turns](concepts/chats-and-turns.md) explains workspace-owned knowledge, mandatory chat-to-team binding, the single-active-turn lifecycle, bounded event replay, context compaction, restore, fork, and nullable usage costs. ## Integration guides - [SDK integration](guides/sdk-integration.md) links the TypeScript, Python, Go, and PHP clients and explains how to choose a compatible release. - [Chat attachments](guides/chat-attachments.md) covers private original uploads, model input capabilities, authorization, and retention. - [Client tools](guides/client-tools.md) covers registering user-scoped tools (`POST /api/v1/tools`), enabling them on agents, verifying EdDSA request signatures against `/.well-known/jwks.json`, and submitting outputs to `/api/v1/atp/v3/chats/{chat_id}/tool-output`. - [Scenario testing](guides/scenario-testing.md) runs your external application against a local scripted provider with real ATP v3 streaming, signed client tools, child agents and replay checks, without live model keys. - [Workspace knowledge](guides/workspace-knowledge.md) covers managing `/wiki`, `/skills`, and `/MEMORY.md` through the workspace files API and wiki ingestion endpoints. - [Image generation](guides/image-generation.md) covers asynchronous image generation and editing: the API returns an accepted job that you poll or receive through a webhook. ## Reference - [HTTP API reference](reference/api.md) summarizes the control-plane and ATP v3 endpoint families and contract version headers. - [Authentication](reference/authentication.md) details `envai_sk_` bearer tokens, JWKS verification, key creation, and Redis `jti` revocation. - [Models](reference/models.md) covers `GET /api/v1/models`, model capabilities, platform defaults, deprecation rules, and catalog synchronization. - [Configuration](reference/configuration.md) documents root `.env` secrets and runtime environment variables for both planes. - [Errors](reference/errors.md) lists HTTP status codes, JSON error envelopes, ATP v3 upgrade errors, and `turn.failed` event codes. ## Canonical protocol and machine-readable contracts - [Agent Team Protocol specification](agent-team-protocol.md) defines wire envelope `v: 3`, event ordering, replay cursors, delegation events, and turn lifecycle rules. - [Shared contracts overview](../packages/contracts/README.md) explains `X-Envai-Contract-Version: 3` negotiation, client tool signing, wiki schemas, and completion terminal snapshots. - [Combined OpenAPI 3.1 specification](../packages/contracts/openapi.yaml) defines request and response schemas for both planes. - [ATP v3 event JSON Schema](../packages/contracts/events.json) defines the machine-readable schema for all ATP v3 event families. ## Self-hosting and contributing - Self-hosting: [Deployment](self-hosting/deployment.md), [Upgrades](self-hosting/upgrades.md), and [Troubleshooting](self-hosting/troubleshooting.md) cover database and Redis topology, migrations, recovery spools, and operational constraints. - Contributing: [Development workflow](contributing/development.md) and [Testing](contributing/testing.md) explain how to work on the Laravel and Go codebases alongside [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md) and [AGENTS.md](../AGENTS.md). ## Documentation formats and questions - [Frequently asked questions](faq.md) covers hosting, resource ownership, ATP transport, API versions, and documentation access for coding agents. - The [documentation website](https://teams.envai.it/docs/) renders these Markdown files and provides [llms.txt](https://teams.envai.it/docs/llms.txt) and [llms-full.txt](https://teams.envai.it/docs/llms-full.txt). It is a static snapshot; use the source revision identified on the website when comparing it with this repository. ## Repository runbooks and historical design notes This directory also contains active operator runbooks and earlier design documents: - [Execution usage and turn recovery](execution-usage-recovery.md), [PostgreSQL and Redis deployment handoff (Italian)](envai-aaas-postgres-redis-deployment.md), [Wiki integration](wiki.md), [Wiki conversion](wiki-conversion.md), and [Wiki verification](wiki-verification.md) document specific subsystem invariants and operator procedures. - [Product architecture notes (Italian)](envai-aaas-progetto.md), [infrastructure notes (Italian)](envai-aaas-infra.md), [orchestration notes (Italian)](envai-aaas-orchestrazione.md), [runtime prompt directives (Italian)](envai-aaas-direttive.md), [subagent lab notes (Italian)](envai-aaas-subagent-lab.md), and [SDK foundation notes](envai-api-sdk-foundation.md) remain in place for engineering context. Some examples in those notes predate ATP v3 or mandatory chat-level team selection; always follow [Agent Team Protocol specification](agent-team-protocol.md) and `packages/contracts/` for the current API contract.