# Create code providers Source: https://docs.agenhq.com/api-reference/code-providers/create-code-providers /coding-agent-api/openapi.json post /api/v1/code-providers Creates a new code providers. Required API key scopes: any of `code-providers:write`, `code-providers:all`, `all:write`, `all:all`. # Delete code providers Source: https://docs.agenhq.com/api-reference/code-providers/delete-code-providers /coding-agent-api/openapi.json delete /api/v1/code-providers/{providerId} Deletes an existing code providers by ID. Required API key scopes: any of `code-providers:write`, `code-providers:all`, `all:write`, `all:all`. # List code providers Source: https://docs.agenhq.com/api-reference/code-providers/list-code-providers /coding-agent-api/openapi.json get /api/v1/code-providers Returns a collection of code providers. Required API key scopes: any of `code-providers:read`, `code-providers:all`, `all:read`, `all:all`. # Update code providers Source: https://docs.agenhq.com/api-reference/code-providers/update-code-providers /coding-agent-api/openapi.json patch /api/v1/code-providers/{providerId} Updates an existing code providers by ID. Required API key scopes: any of `code-providers:write`, `code-providers:all`, `all:write`, `all:all`. # Analyze repository Source: https://docs.agenhq.com/api-reference/repositories/analyze-repository /coding-agent-api/openapi.json post /api/v1/repositories/{id}/analyze Starts a new analysis run for a repository by ID. Required API key scopes: any of `repositories:write`, `repositories:all`, `all:write`, `all:all`. # Create repositories Source: https://docs.agenhq.com/api-reference/repositories/create-repositories /coding-agent-api/openapi.json post /api/v1/repositories Creates a new repositories. Required API key scopes: any of `repositories:write`, `repositories:all`, `all:write`, `all:all`. # Delete repositories Source: https://docs.agenhq.com/api-reference/repositories/delete-repositories /coding-agent-api/openapi.json delete /api/v1/repositories/{id} Deletes an existing repositories by ID. Required API key scopes: any of `repositories:write`, `repositories:all`, `all:write`, `all:all`. # Get repositories Source: https://docs.agenhq.com/api-reference/repositories/get-repositories /coding-agent-api/openapi.json get /api/v1/repositories/{id} Returns a single repositories by ID. Required API key scopes: any of `repositories:read`, `repositories:all`, `all:read`, `all:all`. # Get repository analysis Source: https://docs.agenhq.com/api-reference/repositories/get-repository-analysis /coding-agent-api/openapi.json get /api/v1/repositories/{id}/analysis Returns the latest analysis for a repository by ID. Required API key scopes: any of `repositories:read`, `repositories:all`, `all:read`, `all:all`. # List repositories Source: https://docs.agenhq.com/api-reference/repositories/list-repositories /coding-agent-api/openapi.json get /api/v1/repositories Returns a collection of repositories. Required API key scopes: any of `repositories:read`, `repositories:all`, `all:read`, `all:all`. # Update repositories Source: https://docs.agenhq.com/api-reference/repositories/update-repositories /coding-agent-api/openapi.json patch /api/v1/repositories/{id} Updates an existing repositories by ID. Required API key scopes: any of `repositories:write`, `repositories:all`, `all:write`, `all:all`. # Create sessions Source: https://docs.agenhq.com/api-reference/sessions/create-sessions /coding-agent-api/openapi.json post /api/v1/sessions Creates a new sessions. Required API key scopes: any of `sessions:write`, `sessions:all`, `all:write`, `all:all`. # Get sessions Source: https://docs.agenhq.com/api-reference/sessions/get-sessions /coding-agent-api/openapi.json get /api/v1/sessions/{sessionId} Returns a single sessions by ID. Required API key scopes: any of `sessions:read`, `sessions:all`, `all:read`, `all:all`. # Get the session timeline events Source: https://docs.agenhq.com/api-reference/sessions/get-the-session-timeline-events /coding-agent-api/openapi.json get /api/v1/sessions/{sessionId}/events Returns the events that make up the session timeline shown to users. This includes user and agent messages, as well as progress events emitted while the agent is working, such as file operations, planning updates, repository actions, and other execution steps. Clients can use these events both to render the conversation and to track the agent's progress through the session. Required API key scopes: any of `sessions:read`, `sessions:all`, `all:read`, `all:all`. # List sessions Source: https://docs.agenhq.com/api-reference/sessions/list-sessions /coding-agent-api/openapi.json get /api/v1/sessions Returns a collection of sessions. Required API key scopes: any of `sessions:read`, `sessions:all`, `all:read`, `all:all`. # Send a user message to the agent in a session Source: https://docs.agenhq.com/api-reference/sessions/send-a-user-message-to-the-agent-in-a-session /coding-agent-api/openapi.json post /api/v1/sessions/{sessionId}/messages Sends a new message from the user to the coding agent working in the session. The message is stored as a session event with the `user_message` type, then the agent either starts processing it immediately or the message is queued if the agent is already busy. Required API key scopes: any of `sessions:write`, `sessions:all`, `all:write`, `all:all`. # Update sessions Source: https://docs.agenhq.com/api-reference/sessions/update-sessions /coding-agent-api/openapi.json patch /api/v1/sessions/{sessionId} Updates an existing sessions by ID. Required API key scopes: any of `sessions:write`, `sessions:all`, `all:write`, `all:all`. # Agen CLI Source: https://docs.agenhq.com/cli Reference guide for managing and streaming AI workloads locally. The Agen CLI enables developers to directly integrate AI workloads right where they code. The CLI natively communicates with your existing active sessions to retrieve code created inside Agen isolated sandbox instances. ## Installation Ensure that you have `npm` or `yarn` correctly installed via Node. ```bash theme={null} npm install -g @agenhq/cli ``` ### Setup and Authentication Before pulling any patch files from active Sandbox sessions, confirm you have securely logged in to the Agen web portal inside your local terminal environment. ```bash theme={null} agen login ``` Running the `login` command launches a secure authorization flow directly inside your default web browser. Once finished, an HTTP API token maps uniquely to your verified user account and local `.agen` workspace configurations. ## The Watch Command The real magic happens behind the scenes while the CLI listens to your codebase changes seamlessly. The following command starts a continuous bidirectional synchronization stream: ```bash theme={null} agen watch ``` When you launch this, real-time files created, deleted, and modified via AI changes are parsed, previewed via standard stdout console updates, and integrated into your Git-backed codebase instantly! As your preferred LLM provider generates iterations of variables, code loops, tests, and component styling, `agen watch` streams the exact differences dynamically into your code editor. ## Common Issue: Stale Patches If you shut down the `agen CLI` during an active process, some previously active sessions might be missed. You can simply resume your stream via the same command: ```bash theme={null} agen watch ``` The system automatically pulls the entire directory delta changes (git format patches) previously produced over our real-time messaging network and catches your local codebase repository accurately back up to the current sandbox state. # Get started Source: https://docs.agenhq.com/coding-agent-api/get-started Set up access to the Coding Agent API, create an API key, and make your first requests. ## Get started with the Coding Agent API Use the Coding Agent API to create and manage Agen coding sessions programmatically. Before you make your first request, you need an Agen account, a workspace, an API key, and at least one connected repository. ## Prerequisites Make sure you have the following ready: * An [Agen Web Portal](https://app.agenhq.com/) account * A workspace where you want to run coding sessions * A repository connected to that workspace * An API client such as `curl`, Postman, or your application backend ## Step 1: Set up your Agen workspace 1. Sign in to the [Agen Web Portal](https://app.agenhq.com/). 2. Create a workspace if you do not already have one. 3. Open the workspace and connect the repository you want the agent to work on. 4. Verify the repository has the permissions Agen needs to read, branch, and open changes safely. If you have not done this yet, review the main [Quickstart](/quickstart) guide for a broader walkthrough of setting up Agen. ## Step 2: Get your API key 1. In the [Agen Web Portal](https://app.agenhq.com/), open your workspace. 2. Navigate to the API settings or developer settings area for your workspace. 3. Generate a new API key. 4. Copy the key and store it in a secure secret manager or environment variable. Do not hardcode API keys in source control or expose them in client-side applications. Keep them on a trusted backend or in secure local environment variables. For example: ```bash theme={null} export AGEN_API_KEY="your_api_key_here" ``` ## Step 3: Confirm the API base URL Use the Coding Agent API reference in this docs section together with your API key to authenticate requests. If your team uses a hosted Agen environment, use the API base URL provided with that environment. When sending requests, include your API key as a bearer token: ```bash theme={null} curl https://api.agen.ai/v1/sessions \ -H "Authorization: Bearer $AGEN_API_KEY" ``` ## Step 4: Make your first API request A common first step is to inspect the available endpoints in this reference and then create or manage a session for a repository in your workspace. You can use the interactive API reference on this page set to: * Review available endpoints * Understand request and response schemas * Test requests with your API key in a safe development environment ## Next steps Explore the full Coding Agent API reference and available endpoints. Review the session schema used by the Coding Agent API. # Code provider Source: https://docs.agenhq.com/coding-agent-api/schemas/code-provider A code provider either a gitlab or github personal access token. The code providers are used by the agents to connect to the user code, push changes, create commits, merge pull requests, etc. # Repository Source: https://docs.agenhq.com/coding-agent-api/schemas/repository A code repository, which can be connected to an agent to allow it to read and write code. # Session Source: https://docs.agenhq.com/coding-agent-api/schemas/session A session represents an instance of an agent's execution. It contains information about the agent's state, including its current step, status, and any errors that may have occurred during execution. # Secure Sandboxes Source: https://docs.agenhq.com/essentials/sandboxes Understand how Agen isolates your AI coding sessions to protect your codebase. ## What is an Agen Sandbox? An **Agen Sandbox** is a secure, ephemeral environment running in a Dockerized container where AI agents can safely interact with your repository. When you create a new AI session via Agen, we immediately spin up an isolated virtual machine. The AI is granted restricted access strictly to this sandbox container, allowing it to modify files, resolve dependencies, and compile code. ### Why Sandboxes Matter Instead of running untrusted AI scripts or experimental, AI-generated configurations directly on your local development machine (which might alter your main workspace or leak sensitive credentials), the **sandbox ensures security by design.** The agent is free to browse and alter the codebase within the container. You, as the developer, review all these isolated changes. 1. **Safety First**: Your local development machine or production environment is entirely unaffected by mistakes the AI might make. 2. **Immutable Clean Slate**: Every new session boots a fresh environment. There is no lingering state from previous runs. 3. **No Direct Code Spills**: Any generated file changes must be explicitly synced and approved via the `agen` CLI before they affect your local system. ## Sandbox Capabilities Because our Sandboxes operate as independent Linux environments, they come fully equipped to support robust and active development commands inside the isolated session: * **Git Control**: Sandboxes have full native Git capabilities. The AI can manage branches, commit changes internally, and generate detailed patch diffs for review. * **Real-Time Streaming**: Using our real-time streaming layer, every modification the AI makes inside the sandbox is instantly streamed to your local command line (`agen CLI`), showing a clear before-and-after view of file modifications. ### Seamless Syncing To retrieve code generated within the Sandbox, simply run `agen watch `. You can stream patches generated safely inside the environment directly to your local file system, apply the code you verify, and dismiss the rest. # Scheduled Agents Source: https://docs.agenhq.com/essentials/scheduled-agents Create recurring automation agents that launch sessions on a schedule. Scheduled Agents let you save a prompt and run it automatically on a recurring cadence. They are useful for repeatable work like repository audits, dependency checks, code review sweeps, or any prompt you want Agen to execute without manually creating a new session each time. You can find Scheduled Agents in the left navigation of your workspace. ## Create a Scheduled Agent To create one: 1. Open **Scheduled Agents** in your workspace. 2. Click **New Scheduled Agent**. 3. Fill in the configuration: * **Name**: A clear label for the automation. * **Description**: Optional context for teammates. * **Model**: Choose the LLM the agent should use. * **Enabled**: Turn the automation on or off. * **Schedule interval**: Run every `N` hours, days, or weeks. * **Running days**: Choose which weekdays the automation is allowed to run on. * **Time of day**: Pick the execution time in 15-minute increments. * **Prompt**: The instructions Agen will use when creating each run. * **Budget limits**: Optionally set max budget per run, day, week, and month in USD. 4. Click **Create scheduled agent**. After creation, Agen takes you to the agent detail page where you can review its configuration and run history. ## How scheduling works Each scheduled agent stores both a recurrence interval and a set of allowed weekdays. Examples: * Run every **1 day** at **09:00** on weekdays only. * Run every **1 week** at **14:30**. * Run every **4 hours** while still restricting execution to selected days. The detail page shows the agent's **next run** time and the **last run** time so you can confirm the current schedule. ## Enable or disable an agent Scheduled agents can stay configured without actively running. * **Enabled** agents continue to launch runs according to their schedule. * **Disabled** agents remain saved, but do not execute until re-enabled. You can choose the enabled state when creating the agent and update it later from the edit screen. ## Edit an existing agent Open any scheduled agent and click **Edit** to change its: * prompt * model * enabled status * interval * running days * time of day * budget limits * name or description This is useful when you want to refine the automation without creating a brand new agent. ## Run an agent manually Each scheduled agent detail page includes a **Run now** action. This starts a run immediately using the saved configuration, even if the next scheduled time is later. It is helpful for testing a prompt, validating a model choice, or triggering the workflow on demand. ## Review runs and sessions Every scheduled agent has a **Runs** tab that shows its execution history. For each run, you can review: * run status * when it started and finished * how it was triggered * total token usage * total cost in USD * a link to the session created by that run * any error reason, if the run failed This makes it easy to trace a scheduled automation back to the exact session that performed the work. ## Filter scheduled agents On the main Scheduled Agents page, you can filter by: * **Created by** * **Enabled status** These filters help teams quickly find automations created by a specific workspace member or narrow the list to active versus paused agents. ## Delete a scheduled agent You can delete a scheduled agent from its detail page. Deleting removes the saved scheduled configuration. Existing run history is retained, so past executions are still preserved for reference. ## Best practices * Use descriptive names so teammates understand what the automation does. * Keep prompts focused and repeatable. * Start with budget limits if you expect an agent to run frequently. * Use **Run now** before relying on a new recurring schedule. * Review run history regularly to confirm the automation is still producing useful sessions. # Session Page Source: https://docs.agenhq.com/essentials/session Overview of functionalities available on the Session page in Agen The Session page is your central hub for interacting with AI agents, managing your coding tasks, and reviewing real-time progress. It is designed to give you complete visibility and control over your AI-assisted development workflow. ## Create a New Session Starting a new AI coding session is straightforward and can be initiated directly from the Session page. 1. **Navigate to the Session Page**: Access the Session page from your workspace dashboard. 2. **Click "New Session"**: Look for the primary action button to begin a new task. 3. **Select Repository and Branch**: Choose the repository and specific branch you want the AI to work on. 4. **Choose an AI Model**: Select from the LLMs available in your workspace based on your needs and configurations. 5. **Provide Initial Instructions**: Give the AI a clear, high-level task or goal to start working on. Provide context or point to specific files if necessary. Once created, Agen will automatically provision a secure isolated sandbox and the AI agent will begin its work based on your prompt. ## Session Input The session input area is your primary way to communicate with the active AI agent during a session. * **Task Description**: Use the input box to provide detailed instructions, ask questions, or request specific modifications. * **Context Gathering**: You can ask the AI to explain code, find bugs, or suggest improvements before it starts writing code. * **Iterative Refinement**: As the AI provides feedback or proposes changes, you can use the input to refine the task, provide missing context, or course-correct its approach. * **Commands**: Depending on the specific AI model and integration, you may be able to use specific commands or prompts to guide the agent's behavior. ## Filtering Sessions As you use Agen, you'll accumulate a history of sessions. The filtering functionality helps you quickly find past work or manage active tasks. You can typically filter sessions by: * **Status**: View only active, completed, or failed sessions. * **Repository**: Filter sessions related to a specific project or codebase. * **Date Range**: Find sessions created within a specific timeframe. * **Creator**: See sessions initiated by you or other members of your workspace. By utilizing these filters, you can maintain an organized view of your team's AI-assisted development activities, review past tasks for reference, or monitor ongoing efforts. # Manage Team & Billing Source: https://docs.agenhq.com/essentials/team-billing How to collaborate and manage your Agen workspace. Agen's intuitive web portal is designed to foster team collaboration. ## Workspaces and Collaboration Every organization starts by creating a shared **Workspace**. Within a workspace, the team owner acts as an administrator, deciding which developers gain access to the organization's linked repositories and connected resources. ### Changing Workspace Settings 1. Navigate to the **Settings** menu within the Agen Dashboard. 2. The Settings tab enables administrators to manage overall usage, toggle which features the development team is permitted to use, and view currently open AI sessions. ### Inviting Team Members Inviting a new software engineer into your workflow allows them to track the evolution of your AI processes in real-time, authenticate via local CLI to sync generated code patches locally, and spawn sessions against their own feature branches. To invite your team: * Go to **Settings > Members**. * Add the developers’ email addresses. * Assign appropriate workspace roles (Admin or Contributor). * An email invitation securely prompts them to join the workspace. ## Billing and Usage Managing usage credits allows flexibility as your AI dependency scales. Agen relies on a third-party payment processor to handle secure subscription models or token-based billing options. All workspaces list a **Billing** submenu under Settings that reveals granular details: * **Active Subscriptions**: View your active monthly plan limit. * **Credit Consumption**: Monitor exactly how many AI tokens you’ve used from various providers during developer sessions. * **Invoices**: Seamlessly export current and past invoices. Since Agen allows routing your tasks across various code-generating Large Language Models, usage metrics and analytics help teams choose the AI tool that works effectively for specific codebases, all within your given budget constraints. # Introduction Source: https://docs.agenhq.com/index Welcome to Agen, the ultimate AI agent platform. Here is a detailed overview of what Agen can do for you. Agen is a powerful AI coding platform that seamlessly and securely connects your development workflow with advanced AI tools. Designed to boost your productivity without compromising security, Agen empowers you to delegate coding tasks to AI agents while maintaining full control over your codebase. ## What is Agen? Agen provides a complete ecosystem for AI-assisted software development: * **Secure Isolated Sandboxes**: Every AI coding session runs in a dedicated, isolated sandbox. This ensures the AI can safely write, test, and compile code without ever directly impacting your local machine until you're ready. * **Real-time Code Synchronization**: Through the intuitive Agen CLI, you can watch the AI work in real time. Changes and file patches can be seamlessly synced back to your local repository. * **Collaborative Workspaces**: Manage your projects, invite team members, and configure your preferred AI models and billing settings all from a clean, modern web dashboard. * **Multiple AI Models**: Powered by leading LLM providers, you can choose the best intelligence for your specific task to generate accurate, high-quality code. ## How it works 1. **Create a Workspace**: Start by setting up your workspace and connecting your repository through the Agen web portal. 2. **Launch an AI Session**: Delegate a feature or bug fix to the AI. Agen automatically spins up a secure environment for the agent. 3. **Sync with the CLI**: Use the Agen CLI on your machine to stream the AI's file modifications live. 4. **Review & Apply**: Watch the code evolve, review the generated patches, and confidently apply the finalized code to your project. ## Next Steps Ready to get started? Follow our quickstart guide to set up your first Agen workspace and run your first AI session. # Quickstart Source: https://docs.agenhq.com/quickstart Start using Agen in minutes to securely connect your development workflow with AI agents. ## Get started in three steps Follow these simple steps to set up your first Agen workspace, launch an AI session, and start syncing code manually or via our CLI. ### Step 1: Set up your workspace 1. Navigate to the [Agen Web Portal](https://app.agenhq.com/) (or your hosted instance). 2. Sign up or log in to your account. 3. Create a new **Workspace**. This is where you will manage your repositories, sessions, and team members. 1. Inside your new workspace, click on **Repositories**. 2. Add the Git repository you want the AI to work on. 3. Ensure you have provided the necessary branching permissions so the AI can safely create branches or open pull requests. ### Step 2: Launch an AI Session 1. Go to the **Sessions** tab in your workspace. 2. Click **New Session** and select the repository you just connected. 3. Choose the task you want the AI to perform (e.g., "Refactor the authentication module" or "Create a new React component"). 4. Select your preferred AI model from the options available in your workspace. 5. Start the session. Agen will automatically spin up a **secure, isolated sandbox** for the AI to work without affecting your local machine. ### Step 3: Stream and Sync Code To watch the AI work in real-time and effortlessly sync file modifications to your local environment, install our CLI: ```bash theme={null} npm install -g @agenhq/cli ``` *(Note: Ensure you have Node.js installed).* 1. Authenticate the CLI with your Agen account: ```bash theme={null} agen login ``` 2. Watch the session and sync the patches in real-time: ```bash theme={null} agen watch ``` 3. As the AI Agent writes and tests code inside the sandbox, you will see the files changing locally in real-time! Review the code, run your own tests, and commit the changes when you are satisfied. ## Next steps Now that you have your first AI session running, explore more advanced integrations and tools: Learn how Agen securely isolates AI generated code. Learn how to add team members to your workspace and manage usage. Deep dive into the Agen CLI commands.