diff --git a/docs/src/content/docs/concepts/context-and-artifacts.md b/docs/src/content/docs/concepts/context-and-artifacts.md index bae932b40..55c72044d 100644 --- a/docs/src/content/docs/concepts/context-and-artifacts.md +++ b/docs/src/content/docs/concepts/context-and-artifacts.md @@ -66,3 +66,23 @@ A typical workflow looks like this: - **Use the right branch.** Point the agent at a feature branch if you do not want changes landing directly on `main`. - **Check diffs before pushing.** The file browser shows exactly what changed -- use it. - **Combine with workflows.** Workflows like Bugfix or Spec-kit structure the agent's output so artifacts are consistent and easy to review. + +## Git operations + +After the agent finishes working, you can inspect and manage the resulting Git state directly from the session sidebar. The platform exposes several Git operations that help you review changes, configure remotes, and push code without leaving the UI. + +The agent handles most Git work (committing, branching, pulling) during a session. The operations below let you manage what happens *after* the agent is done. + +| Operation | What it does | +|-----------|-------------| +| **Repository status** | View cloned repositories, their current branch, default branch, and clone state (Cloning, Ready, or Failed). Expand a repository to see all available local branches. | +| **Git status** | Check whether a repository has uncommitted changes, including counts of added and removed files and total lines changed. | +| **Configure remote** | Set or change the remote URL for a repository in the session workspace. The branch defaults to `main`. You need write access to the target repository. | +| **List branches** | View all branches available in a repository's workspace, including branches the agent created during the session. | +| **Merge status** | Check whether changes can merge cleanly into a target branch. The platform reports conflicting files, local change counts, and whether the remote branch exists. | +| **Push to remote** | Push the agent's commits to the configured remote repository. If auto-push is off, use this to deliver changes after reviewing them. | +| **Abandon changes** | Discard all uncommitted changes in a repository, resetting it to the last committed state. This is irreversible. | + +:::note +Some Git operations (push, abandon, create branch) are handled by the agent during the session. The UI operations listed above are available for post-session management and review. +::: diff --git a/docs/src/content/docs/concepts/integrations.md b/docs/src/content/docs/concepts/integrations.md index d99493385..d1133219e 100644 --- a/docs/src/content/docs/concepts/integrations.md +++ b/docs/src/content/docs/concepts/integrations.md @@ -2,7 +2,7 @@ title: "Integrations" --- -Integrations connect external services to the Ambient Code Platform, giving the AI agent access to tools like repository hosting, issue trackers, and document storage. Integrations are **global** -- once configured, they work across all your workspaces. +Integrations connect external services to the Ambient Code Platform, giving the AI agent access to tools like repository hosting, issue trackers, and document storage. Integrations are **user-scoped** -- they are tied to your SSO identity and stored at the cluster level, so once configured, they are available across all your workspaces. MCP tools and runner secrets are workspace-scoped. ## Overview @@ -27,7 +27,7 @@ GitHub integration lets the agent clone repositories, read pull requests, create ### GitHub App 1. Navigate to **Integrations > GitHub**. -2. Click **Connect with GitHub App**. +2. Click **Connect to GitHub App**. 3. You will be redirected to GitHub to authorize the Ambient Code Platform app. 4. Select the organization and repositories you want to grant access to. 5. Complete the OAuth flow -- you will be redirected back to the platform. @@ -46,25 +46,12 @@ PATs do not auto-refresh. You will need to rotate them before they expire. GitLab integration provides the same repository access capabilities as GitHub. -### Setup options - -| Method | Best for | -|--------|---------| -| **OAuth 2.0** (recommended) | Self-managed and SaaS GitLab instances with SSO. | -| **Personal Access Token** | Quick setup or service accounts. | - -### OAuth +### Setup 1. Navigate to **Integrations > GitLab**. -2. Click **Connect with GitLab**. -3. Authorize the application in GitLab. -4. You will be redirected back to the platform once complete. - -### Personal Access Token - -1. In GitLab, go to **Preferences > Access Tokens**. -2. Create a token with `read_repository` and `write_repository` scopes. -3. Paste the token in **Integrations > GitLab** on the platform. +2. Optionally enter your **GitLab instance URL** if you use a self-managed instance (defaults to `https://gitlab.com`). +3. In GitLab, go to **Preferences > Access Tokens** and create a token with `read_repository` and `write_repository` scopes. +4. Paste the token and click **Connect**. ## Jira @@ -73,27 +60,29 @@ Jira integration enables the agent to read issues, create tickets, and update st ### Setup 1. Navigate to **Integrations > Jira**. -2. Click **Connect with Jira**. -3. Complete the OAuth 2.0 authorization flow in Atlassian. +2. Provide your **Jira instance URL** (e.g., `https://yourcompany.atlassian.net`). +3. Enter the **email address** associated with your Jira account. +4. Generate an [API token](https://id.atlassian.com/manage-profile/security/api-tokens) from your Atlassian account and paste it into the **API Token** field. +5. Click **Connect**. Ensure your Atlassian account has the required project permissions. -## Google Workspace +## Google Drive -Google Workspace integration allows the agent to access Google Drive, Calendar, and Gmail. +Google Drive integration allows the agent to access files stored in your Google Drive. ### Setup -1. Navigate to **Integrations > Google Workspace**. -2. Click **Connect with Google Workspace**. -3. Sign in with your Google account and grant the requested permissions. +1. Navigate to **Integrations > Google Drive**. +2. Click **Connect Google Drive**. +3. Sign in with your Google account and grant the requested Drive permissions. 4. You will be redirected back to the platform once authorization is complete. ## Troubleshooting | Symptom | Likely cause | Fix | |---------|-------------|-----| -| Status stays **Disconnected** after setup | OAuth callback did not complete | Retry the connection flow; check for pop-up blockers. | +| Status stays **Disconnected** after setup | Authorization callback did not complete | Retry the connection flow; check for pop-up blockers. | | Token expired errors in sessions | PAT reached its expiry date | Generate a new token and update the integration. | | "Insufficient permissions" in agent logs | Token scope is too narrow | Recreate the token with the required scopes. | | Jira actions fail | Network or permission issue | Verify the Jira URL is reachable from the cluster and that your account has project access. | diff --git a/docs/src/content/docs/concepts/scheduled-sessions.md b/docs/src/content/docs/concepts/scheduled-sessions.md new file mode 100644 index 000000000..a048d46fb --- /dev/null +++ b/docs/src/content/docs/concepts/scheduled-sessions.md @@ -0,0 +1,76 @@ +--- +title: "Scheduled Sessions" +--- + +A **scheduled session** is a recurring AI agent execution that runs automatically on a cron schedule. Each scheduled session is backed by a Kubernetes CronJob that creates a new agentic session at every scheduled interval, using a preconfigured session template. You can use scheduled sessions to automate repetitive tasks such as nightly code reviews, dependency scans, or periodic issue triage -- without manually creating a session each time. + +## Create a scheduled session + +Open a workspace and navigate to the **Scheduled Sessions** tab. Click **New Scheduled Session** to open the creation dialog. + +| Setting | Description | Default | +|---------|------------|---------| +| **Name** | A display name for the schedule (up to 50 characters). | Auto-generated | +| **Schedule** | How often the session runs. Choose a preset or enter a custom cron expression. | Every hour (`0 * * * *`) | +| **Initial prompt** | The prompt sent to the agent when each session starts. This defines the task the agent performs on every run. | *(required)* | +| **Runner type** | The runtime environment for the agent. | Claude Agent SDK | +| **Model** | Which AI model the agent uses. | Claude Sonnet 4.5 | + +### Schedule presets + +The creation dialog offers common presets so you do not need to write cron expressions manually: + +| Preset | Cron expression | +|--------|----------------| +| Every hour | `0 * * * *` | +| Daily at 9:00 AM | `0 9 * * *` | +| Every weekday at 9:00 AM | `0 9 * * 1-5` | +| Weekly on Monday | `0 9 * * 1` | +| Custom | Enter any valid 5-field cron expression | + +When you select or enter a schedule, the dialog shows a human-readable description and previews the next three run times. + +### Session template + +Each scheduled session stores a **session template** that defines the configuration for every session it creates. The template includes the initial prompt, model, runner type, temperature (0.7), max tokens (4,000), and timeout (300 seconds). To change these values after creation, update the scheduled session. + +## Manage schedules + +You can manage scheduled sessions from the **Scheduled Sessions** tab or from the actions menu on each row. + +| Operation | What it does | +|-----------|-------------| +| **Suspend** | Pauses the schedule. No new sessions are created until you resume. Existing running sessions are not affected. | +| **Resume** | Reactivates a suspended schedule. The next session is created at the next scheduled time. | +| **Trigger now** | Immediately creates a one-off session from the schedule's template, regardless of the cron timing. The triggered session is linked to the schedule as a child job. | +| **Update** | Changes the schedule, display name, or session template. You can update any combination of fields. | +| **Delete** | Permanently removes the schedule and its associated Kubernetes CronJob. Child jobs are cleaned up in the background. | + +### Schedule status + +Each scheduled session displays one of two statuses: + +- **Active** -- the schedule is running and creates sessions at the configured interval. +- **Suspended** -- the schedule is paused and does not create new sessions. + +## View run history + +Click a scheduled session name to view its detail page, which lists all sessions created by that schedule. Each run is a standard agentic session that follows the same lifecycle as manually created sessions (Pending, Creating, Running, Completed, Failed, or Stopped). The scheduled sessions list also shows the **Last Run** column, indicating when the most recent session was created. + +The platform retains history for the last 5 successful runs and 3 failed runs per schedule. + +## Concurrency and reliability + +Scheduled sessions use a **forbid-concurrent** policy: if a session from a previous run is still active when the next scheduled time arrives, the new run is skipped. This prevents overlapping agent executions on the same task. + +If the platform is unavailable at the scheduled time, the CronJob has a 5-minute starting deadline. Runs that miss this window are skipped entirely. + +## Use cases + +Scheduled sessions work well for tasks that benefit from regular, unattended execution: + +- **Nightly code health reports** -- run a daily scan that reviews code quality, flags potential issues, and generates a summary. +- **Recurring dependency scans** -- check for outdated or vulnerable dependencies on a weekly cadence. +- **Periodic issue triage** -- have the agent review and categorize new issues every morning before the team starts work. +- **Automated documentation updates** -- regenerate or validate documentation against code changes on a schedule. +- **Regression checks** -- run a suite of verification prompts after each nightly build to catch regressions early. \ No newline at end of file diff --git a/docs/src/content/docs/concepts/sessions.md b/docs/src/content/docs/concepts/sessions.md index f13f3f5e0..b05024ace 100644 --- a/docs/src/content/docs/concepts/sessions.md +++ b/docs/src/content/docs/concepts/sessions.md @@ -11,10 +11,10 @@ Click **New Session** inside a workspace. The creation dialog lets you configure | Setting | Description | Default | |---------|------------|---------| | **Display name** | A label for the session. | Auto-generated | -| **Model** | Which Claude model to use: Claude Sonnet 4.5, Claude Opus 4.6, Claude Opus 4.5, or Claude Haiku 4.5. | Claude Sonnet 4.5 | +| **Model** | Which AI model to use. Available models: Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, Gemini 2.5 Flash (generally available); Claude Opus 4.6, Claude Sonnet 4.6, Gemini 2.5 Pro (feature-gated, visible only when enabled for your workspace). | Claude Sonnet 4.5 | | **Temperature** | Controls response randomness (0 = deterministic, 2 = highly creative). | 0.7 | -| **Max tokens** | Maximum output length per response (100 -- 8,000). | 4,000 | -| **Timeout** | Hard limit on total session duration (60 -- 1,800 seconds). | 300 seconds | +| **Max tokens** | Maximum output length per response. The UI enforces a range of 100--8,000, but the platform API accepts other values. | 4,000 | +| **Timeout** | Hard limit on total session duration. The UI enforces a range of 60--1,800 seconds, but the platform API accepts other values. A separate `inactivityTimeout` field controls how long a session can remain idle before the platform auto-stops it; if omitted, it falls back to the project-level setting and then to a 24-hour default. | 300 seconds | After the session is created, you can attach repositories and select a workflow from the session sidebar. See [Context & Artifacts](../context-and-artifacts/) and [Workflows](../workflows/) for details. @@ -62,6 +62,24 @@ At any moment the agent is in one of three states: If the agent is heading in the wrong direction while it is still **Working**, you can send a new message at any time. The agent will read your message after its current tool call finishes and adjust course. +## Human-in-the-loop + +Sometimes the agent needs your input before it can continue. When this happens, the agent pauses and presents a **question panel** in the chat. The agent's status changes to `waiting_input` until you respond. After you submit your answer, the agent resumes work automatically. + +### Question types + +The question panel supports three input styles depending on what the agent needs to know: + +- **Free-text** -- an open text field for you to type any response. +- **Single-select** -- a list of radio buttons when the agent offers predefined choices. An **Other** option lets you type a custom answer if none of the choices fit. +- **Multi-select** -- a list of checkboxes when the agent wants you to pick one or more options. + +### Multiple questions at once + +When the agent has several questions, the panel displays them in a **tabbed interface**. Each tab shows one question, and a counter tracks how many you have answered. After you select an answer the panel auto-advances to the next tab. You can click any tab to revisit a previous answer before submitting. + +Once all questions are answered, click **Submit** to send your responses and let the agent continue. + ## Session operations | Operation | What it does | @@ -69,13 +87,17 @@ If the agent is heading in the wrong direction while it is still **Working**, yo | **Stop** | Gracefully halts the agent. You can resume later. | | **Resume** | Resumes a stopped session from where it left off. | | **Clone** | Creates a new session with the same configuration and repos -- useful for trying a different approach. Chat history is not copied. | -| **Export** | Exports the chat history in one of three formats: Markdown, PDF, or Google Drive. | +| **Export** | Downloads session data and offers Markdown or PDF export. If the session is running and Google Drive is connected, you can also save directly to your Drive. | | **Delete** | Permanently removes the session and its data. | +## Feedback + +You can rate any agent response with a thumbs-up or thumbs-down button that appears alongside messages in the chat. Clicking either button opens a feedback modal where you can optionally add a comment explaining what went well or what could be improved. The platform sends your rating to Langfuse for observability and quality tracking, automatically associating it with the session, message, user, active workflow, and trace so that teams can analyze agent performance over time. + ## Tips for effective sessions - **Be specific in your first message.** A clear prompt saves back-and-forth. Instead of "fix the bug," try "the login endpoint in `auth.go` returns 500 when the token is expired -- fix the error handling." - **Attach the right repos.** The agent can only see code that has been added as context. -- **Pick the right model.** Sonnet 4.5 is fast and cost-effective for most tasks. Opus 4.6 excels at complex multi-step reasoning. +- **Pick the right model.** Sonnet 4.5 is fast and cost-effective for most tasks. Opus 4.6 excels at complex multi-step reasoning (if enabled for your workspace). - **Use workflows for structured tasks.** If there is a workflow that matches your goal (bug fix, triage, spec writing), attach it from the session sidebar to give the agent a proven plan. - **Review tool calls.** Expanding tool-use blocks lets you verify what the agent actually did before merging its changes. diff --git a/docs/src/content/docs/concepts/workspaces.md b/docs/src/content/docs/concepts/workspaces.md index b910fb417..c2084edbd 100644 --- a/docs/src/content/docs/concepts/workspaces.md +++ b/docs/src/content/docs/concepts/workspaces.md @@ -29,10 +29,11 @@ Each workspace carries its own configuration. Open **Settings** from the workspa ### Storage -By default, session data is stored in a shared storage backend. If your organization requires data isolation you can configure a **custom S3-compatible bucket** per workspace: +Session state is stored using a cluster-wide S3-compatible backend (such as MinIO) configured by the platform administrator. -- Bucket name, endpoint, region -- Access key and secret key +:::note +Custom S3-compatible storage configuration per workspace is a planned feature. Currently, all workspaces share the cluster-wide storage backend. +::: ### Secrets @@ -45,25 +46,107 @@ Secrets are stored securely and are only injected into session pods at runtime. ## Sharing and permissions -You can share a workspace with individual users or groups. Each share is assigned one of three roles: +You can share a workspace with individual **users** or **groups**. +When you grant a permission, the platform creates a Kubernetes `RoleBinding` in the workspace namespace that maps the subject to one of three ClusterRoles. + +The user who creates a workspace is automatically assigned the **Admin** role. + +### Roles + +Each role is cumulative -- higher roles include all capabilities of lower roles. | Role | Capabilities | |------|-------------| -| **View** | See sessions, read chat history and artifacts. Cannot create or modify. | -| **Edit** | Everything in View, plus create sessions, send messages, and manage repos. | -| **Admin** | Everything in Edit, plus manage workspace settings, secrets, and sharing. | +| **View** | See sessions and their status. Read chat history and browse artifacts. View workspace settings, integrations, and storage (read-only). | +| **Edit** | Everything in View, plus create, stop, and delete sessions. Send messages to running sessions. Add repositories and manage workflows. | +| **Admin** | Everything in Edit, plus manage workspace settings, secrets, sharing, and API keys. Grant and revoke permissions for other users and groups. | + +### Granting access + +1. Open **Settings > Sharing** in the workspace sidebar. +2. Click **Grant Permission**. +3. Choose whether you are sharing with a **User** or a **Group**. +4. Enter the subject name and select a role. +5. Click **Grant Permission** to confirm. -To invite someone, go to **Settings > Sharing**, search for a user or group, and pick a role. +Only users with the Admin role can grant permissions. + +### Revoking access + +To remove access, click the delete icon next to any entry in the sharing table. +The user or group immediately loses access to the workspace. ## API keys -For programmatic access -- CI/CD pipelines, scripts, or external tooling -- you can create **workspace-scoped API keys**. +For programmatic access -- CI/CD pipelines, scripts, or external tooling -- you can create **workspace-scoped API keys**. Each key is backed by a dedicated Kubernetes ServiceAccount and bound to a role, so it has the same permission model as a human user. + +### Creating an API key 1. Navigate to **Settings > API Keys**. -2. Click **Create API Key**. -3. Copy the key immediately; it will not be shown again. +2. Click **Create Key**. +3. Fill in the required fields: + +| Field | Required | Description | +|-------|----------|-------------| +| **Name** | Yes | A label to identify the key (for example, `my-ci-key`). Maximum 64 characters. | +| **Description** | No | Optional context such as "Used by CI pipelines". Maximum 200 characters. | +| **Role** | Yes | The permission level for the key. Defaults to **Edit**. | +| **Token Lifetime** | Yes | How long the key remains valid. Defaults to **90 days**. | + +The available roles match the workspace sharing roles: + +| Role | Capabilities | +|------|-------------| +| **View** | Read sessions, chat history, and artifacts. | +| **Edit** | Everything in View, plus create sessions, send messages, and manage repos. | +| **Admin** | Everything in Edit, plus manage workspace settings, secrets, and sharing. | + +Choose a token lifetime based on your use case: + +| Lifetime | Seconds | Typical use case | +|----------|---------|------------------| +| 1 day | 86,400 | Short-lived CI jobs or one-time scripts | +| 7 days | 604,800 | Weekly pipeline runs | +| 30 days | 2,592,000 | Monthly rotation schedules | +| 90 days | 7,776,000 | General-purpose automation (default) | +| 1 year | 31,536,000 | Long-running integrations | +| No expiration | -- | Persistent service keys that you rotate manually | + +4. Click **Create Key**. + +### Copying the key + +After creation, the platform displays the full key **exactly once**. Copy it immediately and store it in a secure location such as a secrets manager. You cannot retrieve the key value after you close the dialog. + +### Using the key + +Pass the key as a Bearer token in the `Authorization` header: + +```bash +curl -H "Authorization: Bearer " \ + https:///api/projects//sessions +``` + +Replace ``, ``, and `` with your actual values. + +### Managing keys + +Open **Settings > API Keys** to view all active keys for the workspace. The key list shows: + +- **Name** and **description** -- identify each key at a glance. +- **Created** -- how long ago the key was created. +- **Last used** -- when the key was last used to authenticate a request, or "Never" if unused. +- **Role** -- the permission level assigned to the key. + +To revoke a key, click the delete icon next to it and confirm. Revocation is immediate -- any system using that key loses access as soon as you confirm. + +### Security best practices -Each API key is assigned an explicit role -- **Admin**, **Edit**, or **View** (defaults to Edit) -- that controls what the key can do. Keys can be revoked at any time. +- **Treat API keys like credentials.** Do not commit them to version control or share them in plaintext. +- **Use the minimum required role.** If a pipeline only reads session results, assign the **View** role. +- **Set an expiration.** Prefer a finite lifetime and rotate keys before they expire. +- **Rotate keys regularly.** Create a replacement key, update your integrations, then revoke the old key. +- **Revoke unused keys.** Check the "Last used" column periodically and delete keys that are no longer in use. ## Best practices diff --git a/docs/src/content/docs/development/architecture.md b/docs/src/content/docs/development/architecture.md index 866a386c5..8a8181df8 100644 --- a/docs/src/content/docs/development/architecture.md +++ b/docs/src/content/docs/development/architecture.md @@ -23,12 +23,12 @@ sequenceDiagram participant Job as Runner Pod User->>Frontend: Create session - Frontend->>Backend: POST /sessions + Frontend->>Backend: POST /api/projects/{project}/agentic-sessions Backend->>K8s: Create AgenticSession CR Operator->>K8s: Watch detects new CR Operator->>K8s: Create Job + Secret + PVC K8s->>Job: Schedule pod - Job->>Job: Clone repos, run Claude CLI + Job->>Job: Clone repos, run AI agent Job->>K8s: Update CR status Frontend->>K8s: Stream CR updates Frontend->>User: Display progress @@ -42,7 +42,7 @@ sequenceDiagram **Operator** -- Go controller built with controller-runtime. Watches AgenticSession CRDs and reconciles desired state by creating Jobs, Secrets, and PVCs with proper owner references. -**Runner** -- Python process that runs inside each Job pod. Wraps the Claude Code CLI, streams output back to the CR status, and handles graceful shutdown on timeout or cancellation. +**Runner** -- Polymorphic AG-UI server that runs inside each Job pod. Supports multiple AI provider bridges (Claude Agent SDK, Gemini CLI, LangGraph), streams output back to the CR status, and handles graceful shutdown on timeout or cancellation. **Frontend** -- NextJS application with Shadcn UI components. Provides the session creation dialog, real-time chat interface, and workspace management. Uses React Query for server state. @@ -50,6 +50,49 @@ sequenceDiagram --- +## Runner types + +Runner types are configurable execution environments that determine which AI framework processes a session. Each runner type maps to a **bridge** -- a Python class that implements the `PlatformBridge` interface and adapts a specific AI framework to the platform's AG-UI event protocol. + +### Available bridges + +The runner resolves which bridge to load from the `RUNNER_TYPE` environment variable, defaulting to `claude-agent-sdk`: + +| Bridge | Framework | Provider | Filesystem | MCP | Tracing | Session persistence | +|--------|-----------|----------|------------|-----|---------|---------------------| +| Claude Agent SDK | `claude-agent-sdk` | `anthropic` | Yes | Yes | Langfuse | Yes | +| Gemini CLI | `gemini-cli` | `google` | Yes | Yes | Langfuse | No | +| LangGraph | `langgraph` | configurable | No | No | LangSmith | No | + +Each bridge declares its capabilities through a `FrameworkCapabilities` object. The frontend reads these capabilities from the `/capabilities` endpoint and hides UI panels that do not apply -- for example, the file browser is hidden for LangGraph sessions because that bridge sets `file_system=False`. Tracing values in the table reflect supported tracers; actual availability depends on whether tracing credentials (such as Langfuse keys) are configured in the deployment. A `ReplayBridge` also exists for testing and development but is not used in production. + +### Model-to-runner mapping + +The model registry (`models.json`) assigns a `provider` field to each model. When a user selects a model, the platform uses the provider to determine which runner type handles the session: + +- **`anthropic`** models (Claude Sonnet, Opus, Haiku) route to the `claude-agent-sdk` runner. +- **`google`** models (Gemini Flash, Pro) route to the `gemini-cli` runner. + +Some models are feature-gated and only appear when the corresponding feature flag is enabled. + +### Capability differences + +Bridges expose different subsets of agent features depending on framework support: + +- **`agentic_chat`** -- Interactive multi-turn conversation (all bridges). +- **`human_in_the_loop`** -- Pause execution to collect user input (Claude, LangGraph). +- **`thinking`** -- Extended thinking / chain-of-thought display (Claude only). +- **`shared_state`** -- Share state between turns within a session (Claude, LangGraph). +- **`backend_tool_rendering`** -- Render tool calls and results server-side (Claude, Gemini). + +### Runner type registry + +Runner types are defined in the **agent registry**, a JSON file mounted from a ConfigMap at `/config/registry/agent-registry.json`. Each entry is an `AgentRuntimeSpec` that specifies the container image, port, environment variables, sandbox configuration, authentication requirements, and an optional feature gate. + +The backend loads and caches the registry in memory (60-second TTL) and exposes it through `GET /api/projects/{project}/runner-types`. Entries with a `featureGate` are filtered out unless the corresponding flag is enabled, with support for workspace-scoped overrides via a separate ConfigMap. This design allows operators to add new runner types or gate experimental frameworks without redeploying the backend. + +--- + ## Key architectural decisions The project maintains [Architectural Decision Records](https://github.com/ambient-code/platform/tree/main/docs/internal/adr) for the full rationale behind each choice. The major decisions: diff --git a/docs/src/content/docs/ecosystem/amber.md b/docs/src/content/docs/ecosystem/amber.md index 646750d1f..15e23f93a 100644 --- a/docs/src/content/docs/ecosystem/amber.md +++ b/docs/src/content/docs/ecosystem/amber.md @@ -2,7 +2,7 @@ title: "Amber" --- -[**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered colleague. She is a codebase intelligence agent that reads your repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Think of Amber as a senior engineer who never forgets a file, never skips a lint check, and is always available. +[**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered codebase intelligence agent. Amber reads your repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Amber retains full awareness of every file, runs every lint check, and is always available. ## What Amber can do @@ -33,7 +33,7 @@ The most common way to work with Amber is to create a session from the platform 3. Optionally select a **workflow** (such as Bugfix or Triage) to give Amber a structured plan. 4. Write your prompt and start the session. -Once running, Amber appears in the chat interface just like any other session. You can ask questions, request changes, and review her work in real time. She shows you every tool call she makes -- file reads, edits, shell commands, searches -- so you always know what happened. +Once running, Amber appears in the chat interface just like any other session. You can ask questions, request changes, and review the results in real time. Amber displays every tool call it makes -- file reads, edits, shell commands, searches -- so you always know what happened. **Example prompts for interactive sessions:** @@ -44,15 +44,15 @@ Once running, Amber appears in the chat interface just like any other session. Y ### GitHub automation -Amber can also work autonomously via GitHub. She can be triggered by GitHub events such as issue creation or webhook integrations, allowing her to analyze issues, implement fixes, and open pull requests without you needing to open the platform UI. +Amber can also work autonomously via GitHub. GitHub events such as issue creation or webhook integrations can trigger Amber to analyze issues, implement fixes, and open pull requests without you needing to open the platform UI. -The specific trigger methods depend on your deployment configuration. Common approaches include GitHub Actions workflows that invoke Amber on issue events, webhook integrations, and scheduled jobs. +The specific trigger methods depend on your deployment configuration. Common approaches include GitHub Actions workflows that start Amber on issue events, webhook integrations, and scheduled jobs. -Amber creates a feature branch, runs linters and tests, and opens a PR linked back to the original issue. By default she does not merge her own PRs, though this can be configured via the `AUTO_MERGE_ENABLED` setting. +Amber creates a feature branch, runs linters and tests, and opens a PR linked back to the original issue. By default, Amber does not merge its own PRs -- a human must review and merge. ## Workflows that pair well with Amber -Amber works with any prompt, but she is especially effective when paired with a workflow. Workflows give her a structured plan to follow, which improves consistency and output quality. +Amber works with any prompt, but it is especially effective when paired with a workflow. Workflows provide a structured plan to follow, which improves consistency and output quality. | Workflow | When to use it with Amber | |----------|--------------------------| @@ -65,11 +65,11 @@ See [Workflows](../concepts/workflows) for the full list and details on creating ## Amber's capabilities -Under the hood, Amber has access to the same toolset as any session on the platform, plus domain knowledge that makes her particularly effective at codebase work. +Under the hood, Amber has access to the same toolset as any session on the platform, plus domain knowledge that makes it particularly effective at codebase work. ### Repository access -Amber reads and writes files across every repository attached to the session. She understands directory structures, import graphs, and language-specific patterns. When you attach multiple repositories, she can reason across all of them -- for instance, tracing how a backend API change affects the frontend. +Amber reads and writes files across every repository attached to the session. It parses directory structures, import graphs, and language-specific patterns. When you attach multiple repositories, Amber can reason across all of them -- for instance, tracing how a backend API change affects the frontend. ### Tool use @@ -83,13 +83,13 @@ During a session, Amber uses tools to do real work: ### Standards awareness -Amber reads your project's `CLAUDE.md` and any workflow instructions to understand your team's conventions. She follows your coding standards, commit message format, testing requirements, and tooling preferences. If your project says "use `gofmt`" or "zero `any` types in TypeScript," Amber enforces that in her own work. +Amber reads your project's `CLAUDE.md` and any workflow instructions to apply your team's conventions. It follows your coding standards, commit message format, testing requirements, and tooling preferences. If your project says "use `gofmt`" or "zero `any` types in TypeScript," Amber enforces that in its own output. ### Confidence and transparency -Amber tells you what she is doing and why. She shows her reasoning, flags uncertainty, and asks before making risky changes. When she opens a pull request, it includes: +Amber reports what it is doing and why. It shows its reasoning, flags uncertainty, and prompts for confirmation before making risky changes. When Amber opens a pull request, it includes: -- What she changed and why. +- What changed and why. - A confidence level (high, medium, or low). - Rollback instructions in case something goes wrong. - A risk assessment of the change's blast radius. @@ -98,14 +98,14 @@ Amber tells you what she is doing and why. She shows her reasoning, flags uncert **Be specific.** A prompt like "fix the bug in the login endpoint where expired tokens return 500 instead of 401" will get a targeted fix. A prompt like "make the code better" will get a generic response. -**Point to files.** If you know which files are involved, mention them. Amber will focus her analysis instead of scanning the entire codebase. +**Point to files.** If you know which files are involved, mention them. Amber focuses its analysis instead of scanning the entire codebase. -**Provide success criteria.** Tell Amber what "done" looks like: "all tests pass," "coverage above 60%," "no lint warnings." She uses these criteria to evaluate her own work. +**Provide success criteria.** Tell Amber what "done" looks like: "all tests pass," "coverage above 60%," "no lint warnings." Amber uses these criteria to validate its own output. -**Start small.** If you are new to Amber, begin with a low-risk task -- a formatting fix, a missing test, or a code review. As you build confidence in her output, move to larger refactors and autonomous workflows. +**Start small.** If you are new to Amber, begin with a low-risk task -- a formatting fix, a missing test, or a code review. As you build confidence in the output, move to larger refactors and autonomous workflows. -**Use workflows for repeatable tasks.** If you run the same kind of task regularly (bug triage, sprint planning, test coverage), select a workflow. It gives Amber a proven process to follow and produces more consistent output. +**Use workflows for repeatable tasks.** If you run the same kind of task regularly (bug triage, sprint planning, test coverage), select a workflow. Workflows provide a proven process and produce more consistent output. -**Review before merging.** Amber never merges her own pull requests by default. Always review the diff, check the test results, and verify the changes make sense in context. +**Review before merging.** Amber does not merge its own pull requests by default. Always review the diff, check the test results, and verify the changes make sense in context. -**Give feedback.** If Amber's output missed the mark, tell her. She adjusts her approach based on your input within the session. Over time, your team's standards in `CLAUDE.md` and custom workflows encode your preferences so every session starts from a better baseline. +**Give feedback.** If Amber's output missed the mark, provide corrections. Amber adjusts its approach based on your input within the session. Over time, your team's standards in `CLAUDE.md` and custom workflows encode your preferences so every session starts from a better baseline. diff --git a/docs/src/content/docs/extensions/public-api.md b/docs/src/content/docs/extensions/public-api.md new file mode 100644 index 000000000..e6b8a3212 --- /dev/null +++ b/docs/src/content/docs/extensions/public-api.md @@ -0,0 +1,222 @@ +--- +title: "Public API" +--- + +The Public API is a stateless HTTP gateway that provides a simplified REST interface for managing agentic sessions. It proxies authenticated requests to the backend service and never accesses Kubernetes directly. Use it to integrate external tools, scripts, or CI/CD pipelines with the Ambient Code Platform. + +## Authentication + +Every request to the `/v1` endpoints requires a bearer token in the `Authorization` header. The gateway forwards this token to the backend, which performs full validation including signature verification and RBAC enforcement. + +```http +Authorization: Bearer +``` + +The gateway also accepts tokens through the `X-Forwarded-Access-Token` header for compatibility with OAuth proxies. + +## Project context + +All session operations are scoped to a project. Set the project using the `X-Ambient-Project` header: + +```http +X-Ambient-Project: my-project +``` + +If you use a Kubernetes ServiceAccount token, the gateway can extract the project from the token's namespace claim. When both the header and the token specify a project, they must match — a mismatch returns an authentication error to prevent routing attacks. If no project can be resolved from either the header or the token, the gateway returns `400 Bad Request`. + +## Endpoints + +### List sessions + +``` +GET /v1/sessions +``` + +Returns all sessions in the specified project. + +**Response:** + +```json +{ + "items": [ + { + "id": "session-abc123", + "status": "completed", + "task": "Refactor the authentication module", + "model": "claude-sonnet-4-20250514", + "createdAt": "2025-06-15T10:30:00Z", + "completedAt": "2025-06-15T10:45:00Z", + "result": "Refactored auth module to use middleware pattern..." + } + ], + "total": 1 +} +``` + +### Get session details + +``` +GET /v1/sessions/:id +``` + +Returns a single session by ID. + +**Response:** + +```json +{ + "id": "session-abc123", + "status": "running", + "task": "Refactor the authentication module", + "model": "claude-sonnet-4-20250514", + "createdAt": "2025-06-15T10:30:00Z" +} +``` + +### Create a session + +``` +POST /v1/sessions +``` + +Creates a new agentic session. + +**Request body:** + +```json +{ + "task": "Analyze this repository for security issues", + "model": "claude-sonnet-4-20250514", + "repos": [ + { + "url": "https://github.com/org/repo.git", + "branch": "main" + } + ] +} +``` + +| Field | Required | Description | +|-------|----------|-------------| +| `task` | Yes | The prompt or task for the agent to perform | +| `model` | No | Model override (defaults to the project's configured model) | +| `repos` | No | Array of repositories to clone into the session | +| `repos[].url` | Yes | Git repository URL | +| `repos[].branch` | No | Branch to check out | + +**Response** (`201 Created`): + +```json +{ + "id": "session-abc123", + "message": "Session created" +} +``` + +### Delete a session + +``` +DELETE /v1/sessions/:id +``` + +Deletes a session by ID. Returns `204 No Content` on success. + +## Response format + +All session responses use a simplified DTO with the following fields: + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Session name (Kubernetes resource name) | +| `status` | string | Normalized status: `pending`, `running`, `completed`, `failed`, or `stopped` | +| `task` | string | The task prompt that was submitted | +| `model` | string | Model used for the session (omitted if not set) | +| `createdAt` | string | ISO 8601 creation timestamp | +| `completedAt` | string | ISO 8601 completion timestamp (omitted if not finished) | +| `result` | string | Session result text (omitted if not completed) | +| `error` | string | Error message (omitted if no error) | + +## Phase state mapping + +The gateway normalizes Kubernetes phase values into simplified statuses: + +| API status | Kubernetes phases | +|------------|-------------------| +| `pending` | `Pending`, `Creating`, `Initializing` | +| `running` | `Running`, `Active` | +| `completed` | `Completed`, `Succeeded` | +| `failed` | `Failed`, `Error` | + +Phases not listed above (such as `Stopped` or `Stopping`) pass through as-is without normalization. If no status is set on the underlying resource, the gateway defaults to `pending`. + +## Rate limiting + +The gateway enforces per-IP rate limiting on all `/v1` endpoints. Health, readiness, and metrics endpoints are excluded from rate limiting. + +| Setting | Default | Environment variable | +|---------|---------|---------------------| +| Requests per second | 100 | `RATE_LIMIT_RPS` | +| Burst size | 200 | `RATE_LIMIT_BURST` | + +When the rate limit is exceeded, the gateway returns `429 Too Many Requests`: + +```json +{ + "error": "Rate limit exceeded", + "retry_after": "1s" +} +``` + +## Health endpoints + +These endpoints do not require authentication. + +| Endpoint | Description | +|----------|-------------| +| `GET /health` | Returns `{"status": "ok"}` when the service is running | +| `GET /ready` | Returns `{"status": "ready"}` when the service can accept traffic | +| `GET /metrics` | Prometheus-format metrics | + +## Configuration + +Configure the gateway with environment variables: + +| Variable | Default | Description | +|----------|---------|-------------| +| `BACKEND_URL` | `http://backend-service:8080` | Internal backend service URL | +| `BACKEND_TIMEOUT` | `30s` | Timeout for backend requests (Go duration format) | +| `PORT` | `8081` | Port the gateway listens on | +| `RATE_LIMIT_RPS` | `100` | Maximum requests per second per IP | +| `RATE_LIMIT_BURST` | `200` | Maximum burst size per IP | +| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000,http://localhost:8080,https://*.apps-crc.testing` | Comma-separated list of allowed CORS origins | +| `GIN_MODE` | `release` | Gin framework mode (`release`, `debug`, `test`) | + +## Error responses + +All errors use a consistent JSON format: + +```json +{ + "error": "Description of the error" +} +``` + +Common error codes: + +| Status | Meaning | +|--------|---------| +| `400 Bad Request` | Invalid project name, session ID, or request body | +| `401 Unauthorized` | Missing or invalid bearer token | +| `429 Too Many Requests` | Rate limit exceeded | +| `502 Bad Gateway` | Backend service is unavailable | + +## Input validation + +The gateway validates all path parameters against Kubernetes naming rules before forwarding requests. Project names and session IDs must: + +- Start with a lowercase letter or digit +- Contain only lowercase letters, digits, or hyphens +- End with a lowercase letter or digit +- Be at most 63 characters + +Invalid names are rejected with `400 Bad Request` before reaching the backend. \ No newline at end of file diff --git a/docs/src/content/docs/getting-started/cli.md b/docs/src/content/docs/getting-started/cli.md new file mode 100644 index 000000000..7778b1739 --- /dev/null +++ b/docs/src/content/docs/getting-started/cli.md @@ -0,0 +1,379 @@ +--- +title: "CLI Reference" +--- + +`acpctl` is the command-line interface for the Ambient Code Platform. You can use it to create and manage sessions, switch between projects, and automate workflows from your terminal. + +## Install acpctl + +Download the latest binary from your organization's ACP deployment or build it from source: + +```bash +cd components/ambient-cli +go build -o acpctl ./cmd/acpctl +``` + +Move the binary to a directory in your `PATH`: + +```bash +sudo mv acpctl /usr/local/bin/ +``` + +Verify the installation: + +```bash +acpctl version +``` + +## Authentication + +### Log in + +Authenticate with the ACP API server by providing an access token. The token is saved to your local configuration file. + +```bash +acpctl login --token +``` + +You can also specify the API server URL and a default project in the same command: + +```bash +acpctl login --token --url https://acp.example.com --project my-project +``` + +If the server uses a self-signed certificate, add the `--insecure-skip-tls-verify` flag: + +```bash +acpctl login --token --url https://acp.example.com --insecure-skip-tls-verify +``` + +You can pass the server URL as a positional argument instead of using `--url`: + +```bash +acpctl login https://acp.example.com --token +``` + +| Flag | Description | +|---|---| +| `--token` | Access token (required) | +| `--url` | API server URL (default: `http://localhost:8000`) | +| `--project` | Default project name | +| `--insecure-skip-tls-verify` | Skip TLS certificate verification | + +### Log out + +Remove saved credentials from the configuration file: + +```bash +acpctl logout +``` + +### Check your identity + +Display the current user, token expiration, API URL, and active project: + +```bash +acpctl whoami +``` + +Example output for a JWT token: + +``` +User: jane.doe +Email: jane@example.com +Expires: 2026-04-01T12:00:00Z +API URL: https://acp.example.com +Project: my-project +``` + +## Configuration + +`acpctl` stores configuration in a JSON file. The default location depends on your operating system: `~/.config/ambient/config.json` on Linux, `~/Library/Application Support/ambient/config.json` on macOS. Override the location with the `AMBIENT_CONFIG` environment variable. + +### Get a configuration value + +```bash +acpctl config get +``` + +Valid keys: `api_url`, `project`, `pager`, `access_token` (redacted in output). + +```bash +acpctl config get api_url +# https://acp.example.com +``` + +### Set a configuration value + +```bash +acpctl config set +``` + +Valid keys: `api_url`, `project`, `pager`. + +```bash +acpctl config set api_url https://acp.example.com +acpctl config set project my-project +``` + +### Configuration keys + +| Key | Description | Default | +|---|---|---| +| `api_url` | ACP API server URL | `http://localhost:8000` | +| `project` | Active project name | (none) | +| `pager` | Pager program for output | (none) | +| `access_token` | Authentication token (set via `login`) | (none) | +| `request_timeout` | Request timeout in seconds | `30` | +| `polling_interval` | Watch polling interval in seconds | `2` | +| `insecure_tls_verify` | Skip TLS verification | `false` | + +## Project context + +Most commands operate within a project context. Set the active project before creating or managing sessions. + +### Set the active project + +```bash +acpctl project set my-project +``` + +Or use the shorthand: + +```bash +acpctl project my-project +``` + +The CLI validates that the project exists on the server before saving it to your configuration. + +### View the current project + +```bash +acpctl project current +``` + +Or use the shorthand (no arguments): + +```bash +acpctl project +``` + +### List all projects + +```bash +acpctl project list +``` + +## Manage projects + +### Create a project + +```bash +acpctl create project --name my-project +``` + +Optionally set a display name and description: + +```bash +acpctl create project --name my-project --display-name "My Project" --description "Team workspace" +``` + +| Flag | Description | +|---|---| +| `--name` | Project name (required). Must be lowercase alphanumeric with hyphens, 63 characters max. | +| `--display-name` | Human-readable display name | +| `--description` | Project description | +| `-o, --output` | Output format: `json` | + +### List projects + +```bash +acpctl get projects +``` + +Get a specific project: + +```bash +acpctl get project my-project +``` + +### View project details + +```bash +acpctl describe project my-project +``` + +Output is JSON with the full project resource. + +### Delete a project + +```bash +acpctl delete project my-project +``` + +Add `-y` to skip the confirmation prompt: + +```bash +acpctl delete project my-project -y +``` + +## Manage sessions + +### Create a session + +A project context must be set before you create a session. + +```bash +acpctl create session --name fix-login-bug --prompt "Fix the null pointer in the login handler" --repo-url https://github.com/org/repo +``` + +| Flag | Description | +|---|---| +| `--name` | Session name (required) | +| `--prompt` | Task prompt for the agent | +| `--repo-url` | Repository URL to clone | +| `--model` | LLM model to use | +| `--max-tokens` | Maximum output tokens | +| `--temperature` | LLM temperature (0.0-1.0) | +| `--timeout` | Session timeout in seconds | +| `-o, --output` | Output format: `json` | + +### List sessions + +```bash +acpctl get sessions +``` + +Get a specific session: + +```bash +acpctl get session +``` + +Output in JSON format: + +```bash +acpctl get sessions -o json +``` + +Use wide output for additional columns: + +```bash +acpctl get sessions -o wide +``` + +| Flag | Description | +|---|---| +| `-o, --output` | Output format: `json` or `wide` | +| `--limit` | Maximum number of items to return (default: `100`) | +| `-w, --watch` | Watch for real-time session changes | +| `--watch-timeout` | Timeout for watch mode (default: `30m`, e.g. `1h`, `10m`) | + +### Watch sessions + +Monitor session changes in real time: + +```bash +acpctl get sessions -w +``` + +The watch uses gRPC streaming when available. If the server does not support streaming, the CLI falls back to polling. Press `Ctrl+C` to stop watching. + +### View session details + +```bash +acpctl describe session +``` + +Output is JSON with the full session resource. + +### Start a session + +Start a session that is in a stopped or pending state: + +```bash +acpctl start +``` + +### Stop a session + +Stop a running session: + +```bash +acpctl stop +``` + +### Delete a session + +```bash +acpctl delete session +``` + +Add `-y` to skip the confirmation prompt: + +```bash +acpctl delete session -y +``` + +## Other resources + +You can also manage project settings and users through the `get` and `describe` commands. + +### Project settings + +```bash +acpctl get project-settings +acpctl describe project-settings +acpctl delete project-settings +``` + +Resource aliases: `projectsettings`, `ps`. + +### Users + +```bash +acpctl get users +acpctl describe user +``` + +Resource aliases: `user`, `usr`. + +## Global flags + +| Flag | Description | +|---|---| +| `--insecure-skip-tls-verify` | Skip TLS certificate verification for all commands | +| `--version` | Print the version and exit | + +## Environment variables + +Environment variables override values in the configuration file. + +| Variable | Description | Overrides config key | +|---|---|---| +| `AMBIENT_CONFIG` | Path to the configuration file | (file location) | +| `AMBIENT_API_URL` | API server URL | `api_url` | +| `AMBIENT_TOKEN` | Access token | `access_token` | +| `AMBIENT_PROJECT` | Active project name | `project` | +| `AMBIENT_REQUEST_TIMEOUT` | Request timeout in seconds | `request_timeout` | +| `AMBIENT_POLLING_INTERVAL` | Watch polling interval in seconds | `polling_interval` | + +## Shell completion + +Generate completion scripts for your shell: + +```bash +# Bash +acpctl completion bash > /etc/bash_completion.d/acpctl + +# Zsh +acpctl completion zsh > "${fpath[1]}/_acpctl" + +# Fish +acpctl completion fish > ~/.config/fish/completions/acpctl.fish + +# PowerShell +acpctl completion powershell > acpctl.ps1 +``` + +Restart your shell or source the completion file to enable tab completion. diff --git a/docs/src/content/docs/getting-started/concepts.md b/docs/src/content/docs/getting-started/concepts.md index de5c65d02..472a4c591 100644 --- a/docs/src/content/docs/getting-started/concepts.md +++ b/docs/src/content/docs/getting-started/concepts.md @@ -25,7 +25,7 @@ Sessions have a defined lifecycle: While running, you can interact with the agent through a chat interface, observe its progress in real time, and browse output artifacts. Sessions are configurable: -- **Model** -- Which LLM powers the agent (Claude Sonnet 4.5, Claude Opus 4.6, Claude Opus 4.5, or Claude Haiku 4.5). +- **Model** -- Which LLM powers the agent. Available models include Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, and Gemini 2.5 Flash (generally available), plus Claude Opus 4.6, Claude Sonnet 4.6, and Gemini 2.5 Pro (feature-gated, when enabled by your administrator). - **Temperature** -- Controls response randomness (default: 0.7). - **Max tokens** -- Maximum output tokens per response (default: 4000). - **Timeout** -- Maximum execution time in seconds before the session is stopped (default: 300). @@ -36,14 +36,14 @@ Learn more in [Sessions](../../concepts/sessions/). ## Integrations -Integrations connect ACP to external services so agents can read from and write to the tools your team already uses. Integrations are configured globally and available across all workspaces. +Integrations connect ACP to external services so agents can read from and write to the tools your team already uses. Integrations are user-scoped (tied to your SSO identity) and available across all your workspaces. | Integration | Auth Method | What Agents Can Do | |---|---|---| | **GitHub** | GitHub App or PAT | Clone repos, open PRs, read/comment on issues | -| **GitLab** | OAuth | Clone repos, open merge requests, interact with issues | -| **Jira** | OAuth | Read and update tickets, add comments, transition status | -| **Google Workspace** | OAuth | Access Drive documents, Calendar events, and Gmail for context | +| **GitLab** | Personal Access Token (PAT) | Clone repos, open merge requests, interact with issues | +| **Jira** | API Token (email + token) | Read and update tickets, add comments, transition status | +| **Google Drive** | OAuth | Access Drive files for context | Once connected, every session can use them. diff --git a/docs/src/content/docs/getting-started/quickstart-ui.md b/docs/src/content/docs/getting-started/quickstart-ui.md index fa690c7cb..bab63a42d 100644 --- a/docs/src/content/docs/getting-started/quickstart-ui.md +++ b/docs/src/content/docs/getting-started/quickstart-ui.md @@ -1,16 +1,16 @@ --- -title: "Quickstart" +title: "Quick start" --- -This guide walks you through creating your first AI agent session using the Ambient Code Platform web interface. +Create your first AI agent session using the Ambient Code Platform web interface. -## Sign In +## Sign in ACP uses SSO for authentication -- there is no separate account to create. Navigate to your organization's ACP URL and sign in with your existing credentials. After signing in, you land on the **Workspaces** page. -## Create a Workspace +## Create a workspace Workspaces are project containers that hold your sessions, integrations, and team permissions. @@ -20,7 +20,7 @@ Workspaces are project containers that hold your sessions, integrations, and tea You are now inside your workspace. From here you can configure integrations and start sessions. -## Configure Integrations (Optional) +## Configure integrations (optional) Integrations let agents interact with your external services. You can skip this step and add integrations later. @@ -29,25 +29,25 @@ To connect a service: 1. Open your workspace and navigate to **Settings** > **Integrations**. 2. Select the service you want to connect: - **GitHub** -- Authenticate via GitHub App installation or Personal Access Token. - - **GitLab** -- Authenticate via OAuth. - - **Jira** -- Authenticate via OAuth. - - **Google Workspace** -- Authenticate via OAuth (covers Drive, Calendar, and Gmail). + - **GitLab** -- Authenticate with a Personal Access Token. + - **Jira** -- Authenticate with your Jira instance URL, email, and API token. + - **Google Drive** -- Authenticate via OAuth to access Drive files. 3. Follow the OAuth or token flow to authorize ACP. Once connected, agents in this workspace can read from and write to the linked service. -## Create Your First Session +## Create your first session 1. From your workspace, click **New Session**. 2. In the create session dialog, configure: - **Display name** (optional) -- A human-readable label for the session. - - **Model** -- Select the LLM to use from the dropdown (Claude Sonnet 4.5, Claude Opus 4.6, Claude Opus 4.5, or Claude Haiku 4.5). + - **Model** -- Select the LLM to use from the dropdown. Available models include Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, and Gemini 2.5 Flash (generally available), plus Claude Opus 4.6, Claude Sonnet 4.6, and Gemini 2.5 Pro (feature-gated, when enabled by your administrator). - **Integrations** -- Review the read-only status indicators showing which integrations are connected. 3. Click **Create Session**. The session enters the **Pending** state and begins provisioning. -## Work with the Session +## Work with the session Once the session reaches the **Running** state, the session chat page opens. From here you can: @@ -55,7 +55,7 @@ Once the session reaches the **Running** state, the session chat page opens. Fro - **Add repositories** from the sidebar to give the agent access to your code. - **Select a workflow** from the sidebar to apply a structured task template (e.g., Bugfix, Triage). -## Monitor the Session +## Monitor the session The session moves through these states: @@ -75,10 +75,16 @@ While the session is running you can: - **View logs** to see what the agent is doing in real time. - **Browse Shared Artifacts** in the sidebar accordion to inspect files the agent has created or modified. -## Review Results +## Review results When the session completes: 1. Open the session to see the full conversation and any final output. 2. Expand **Shared Artifacts** in the sidebar to browse files the agent produced. 3. If the agent opened a pull request, follow the link to review it in your source control provider. + +## Keyboard shortcuts + +Press **Cmd+K** (Mac) or **Ctrl+K** (Windows/Linux) to open the command palette. +From the command palette you can quickly navigate to any workspace, jump to settings or integrations, and start a new session. +Type in the search field to filter the available commands and workspaces.