AI Agent Configuration

The AI Agent configuration system gives administrators fine-grained control over agent behavior at two levels: global defaults that apply to all repositories, and per-repository overrides for specific projects. All configuration is managed through REST API endpoints.

Configuration hierarchy

Global defaults live in the Lifecycle global_config table under the aiAgent key. Per-repository overrides are stored in the ai_agent_repo_config table and merged on top of global defaults at runtime.

Fields

How merging works

When a repository has an override, the effective configuration is computed by merging the override on top of global defaults:

• Scalar fields (enabled, maxMessagesPerSession, sessionTTL, systemPromptOverride) — the repository value replaces the global value.
• Array fields (additiveRules, excludedTools, excludedFilePatterns, allowedWritePatterns) — repository values are appended to global values. Duplicates are removed automatically.

Here’s a concrete example. Say your global config looks like this:

And myorg/frontend has this override:

The effective config for myorg/frontend:

Provider and model configuration

The providers field defines which LLM providers and models are available. This is a global-only field — repository overrides cannot change provider configuration.

Each provider entry has the following structure:

Each model entry:

Example with pricing configured:

Caching

Prompt customization

Additive rules

The additiveRules field accepts an array of strings appended to the system prompt. Use this to add organization-specific guidelines, restrict behaviors, or provide extra context.

Because additive rules use additive merge, global rules and repository rules are combined. Set organization-wide rules globally and layer project-specific rules per repository.

System prompt override

The systemPromptOverride field replaces the entire default system prompt. This is a full replacement, not additive.

When set at the repository level, the override applies only to that repository. The scalar merge rule means the repository value fully replaces any global override.

Access control

Excluded tools

The excludedTools field prevents the agent from using specific tools. This is useful for restricting write operations in sensitive repositories.

Available tool names:

• get_k8s_resources
• get_lifecycle_logs
• patch_k8s_resource
• query_database
• get_github_file
• list_github_directory
• update_github_file
• get_issue_comment

Because excluded tools use additive merge, tools excluded at the global level cannot be “un-excluded” at the repository level.

Excluded file patterns

The excludedFilePatterns field accepts glob patterns that restrict which files the agent can access through the GitHub tools.

Validation rules:

Like other array fields, file patterns use additive merge. Global patterns and repository patterns are combined and deduplicated.

Allowed write patterns

The allowedWritePatterns field controls which file paths the agent is permitted to modify through the update_file tool. By default, the agent can only write to lifecycle.yaml and lifecycle.yml (plus any files explicitly referenced in the lifecycle configuration such as Dockerfiles and Helm value files).

To allow the agent to modify additional files, add glob patterns to this field. For example, to allow modifications to Helm charts, Dockerfiles, and Ansible playbooks:

Like other array fields, allowed write patterns use additive merge. Global patterns and repository patterns are combined and deduplicated.

Orchestration limits

These fields control the agent’s internal behavior. They are all global-only settings — repository overrides cannot change them. If omitted, the defaults below are used.

Loop protection

Controls for the agent’s tool-calling loop that prevent runaway behavior.

When a limit is hit, the agent stops and returns an error message to the user explaining what happened.

Context management

Controls how the agent manages conversation context to stay within LLM token limits.

Tool execution

Controls for tool execution behavior and output handling.

Resilience

Controls for error recovery when communicating with LLM providers.

Managing configuration via API

All endpoints are under /api/v2/ai/agent-config. Request and response bodies use JSON.

Global configuration

Get the current global config:

Update the global config:

Returns the updated configuration on success. Returns 400 for validation failures (invalid schema, prompt too long, core tool exclusion, bad file patterns).

Repository overrides

List all repository overrides:

Get a single repository override:

Returns only the override fields, not the merged result. Returns 404 if no override exists.

Get the effective (merged) configuration:

Create or update a repository override:

Uses upsert semantics. Only include the fields you want to override.

Returns the saved override on success. Returns 400 for validation failures.

Delete a repository override:

Soft-deletes the override. The repository reverts to global defaults.

Troubleshooting

Config changes not taking effect

Configuration is cached at multiple layers. The API automatically invalidates caches on update, but if you changed the database directly, you may need to wait:

• In-memory cache — expires after 30 seconds
• Redis cache — expires after 5 minutes

Use the /effective endpoint to confirm what the agent sees.

Cannot exclude a core tool

query_database is required for agent operation. If you include it in excludedTools, the API returns:

Remove it from your exclusion list.

Excluded tool still being used

Array fields use additive merge. If you removed a tool from a repository override but it’s still excluded, check the global config — the tool may be excluded there. Global exclusions cannot be overridden at the repo level.

System prompt override not working as expected

systemPromptOverride completely replaces the built-in prompt, including safety instructions and tool usage guidelines. If the agent behaves unexpectedly, try additiveRules instead — it appends to the default prompt rather than replacing it.