Working with Agents
AI Agents are the “brain” of VeloGit. This guide explains how to configure agents for your organization and how they interact with your repositories.
The Agent Registry
Section titled “The Agent Registry”Every organization has an Agent Registry — navigate to Agents in the sidebar to create and manage your agents.
Configuring an Agent
Section titled “Configuring an Agent”When creating or editing an agent, you configure the following sections.
Identity
Section titled “Identity”- Name: A descriptive name for the agent (e.g., “Security Reviewer”).
- Description: A short summary of what the agent does.
Events
Section titled “Events”Choose which platform events trigger the agent:
push: Triggered on every commit push.pr.created: Triggered when a new pull request is opened.comment.created: Triggered when a comment is added.
An agent must subscribe to at least one event.
Behavior
Section titled “Behavior”- Code reviewer (default): The agent reviews changed files and emits Shadow Fragments — code suggestions visible in the Ghost Workspace.
- Docs sync: The agent keeps a documentation file up to date. Specify the file path (e.g.,
README.mdordocs/api.md) and the agent will propose updates to that file whenever subscribed events fire.
System Prompt
Section titled “System Prompt”The agent’s persona and instructions. Use this to define coding style, review focus areas, and tone. Leave blank to use the built-in prompt.
Optionally pin this agent to a specific LLM config. If unset, the agent uses the organization’s default model.
Capabilities
Section titled “Capabilities”Fine-grained controls over what the agent is allowed to do:
| Capability | Description |
|---|---|
| Post Shadow Fragments | Agent may propose code changes via the Ghost Workspace. |
| Gate votes | Whether the agent can vote on pipeline gate steps: None, Approve, Reject, or Full (both). |
| PR actions | Whether the agent can post PR reviews (Review) or merge pull requests (Merge). |
| Trigger Rituals | Whether the agent may trigger pipeline runs in permitted repositories. |
Repository Scope
Section titled “Repository Scope”By default, an agent has access to all repositories in the organization. To restrict it, enter a comma-separated list of repository names. The agent will only act on events from those repos.
Organization AI Kill Switch
Section titled “Organization AI Kill Switch”The AI Enabled toggle in Organization Settings disables all agent activity for the entire organization instantly — no events will be processed by any agent while it’s off. This is useful during incidents or sensitive deployments.
Organization LLM Config
Section titled “Organization LLM Config”Before agents can run, you must configure at least one LLM Provider at the organization level. Supported providers:
- OpenAI — API key + model (e.g.,
gpt-4o) - Anthropic — API key + model (e.g.,
claude-sonnet-4-5) - Google GenAI — Gemini API key
- AWS Bedrock — credentials + region
VeloGit follows a Bring Your Own Key policy — you retain full control over LLM costs and usage. Organizations on plans that include Velo AI Tokens can use platform-provided keys instead.
Agent Activity Log
Section titled “Agent Activity Log”The Activity section in Organization Settings shows a paginated feed of every action taken by agents in your organization — fragments posted, comments added, reviews submitted, gate votes cast, and errors encountered. Each entry includes the agent name, event type, repository, timestamp, and token usage.
Use the activity log to:
- Audit what agents have done and when
- Debug unexpected agent behavior
- Monitor token consumption across models
Built-in Fallback Agent
Section titled “Built-in Fallback Agent”If no custom push agents are active, VeloGit’s built-in reviewer runs automatically on every push. It produces Shadow Fragments using the organization’s default LLM. Configure a custom agent to override or supplement this behavior.