Configure an agent

Define an agent with skills, model policy, runtime policy, grants, and optional ambient triggers

Create an agent when you want a reusable automation identity for a workspace. A production triage agent, a repository-change agent, and a seller support agent can all use the same resource model with different instructions and policies.

Agent resources are available through the API. Dashboard configuration screens will expose the same fields as product UI.

What you configure

Setting	Purpose
Name and description	Helps users choose the right agent.
Instructions	Defines the agent’s role and operating style.
Skills	Adds reusable behavior such as repository change triage or deployment investigation.
Capabilities	Enables broad modes such as chat, coding, and ambient operation.
Communication style	Controls whether the agent explains work in beginner, intermediate, advanced, expert, or adaptive language. See Communication style.
Model policy	Controls model selection, budget, and whether provider billing is Akua-managed or workspace BYOK.
Runtime policy	Defines when the agent can use a retained runtime, filesystem, shell, or browser.
Grants	Limits which platform resources the agent can read or mutate.
Permission policy	Decides which actions require human approval.
Ambient triggers	Starts work automatically when configured signals match.

Grants

Grants are explicit permissions. Avoid giving an agent broad mutation access when it only needs context.

For agents that prepare repository change requests, the recommended baseline is:

Resource	Actions	Why
repository_change_request	read, create, continue	Read existing change requests, create a reviewable draft, or continue a prior change request when appropriate.
install	read	Inspect deployment state and source configuration.
cluster	read	Gather operational context.
product	read	Understand the packaged software and versions.

Additional actions such as update, close, or accept should be separate grants and can require approval.

Model policy

Agents can use Akua-managed billing or workspace-owned provider credentials. Workspace credentials are referenced through secrets; secret values are not exposed to the agent runtime.

Use budget limits for agents that can run automatically or launch coding work.

Communication style

Agents should match the user’s experience level. A beginner may need “your app keeps restarting” with a suggested next step. An expert may prefer exact resource names, recent events, and the underlying Kubernetes status.

Use an adaptive style when the agent should vary detail within an explicit user, session, or agent default. The agent should not silently change a user’s proficiency level based on writing style.

Communication style should not reduce analysis quality. It changes how findings are explained, not what evidence the agent gathers or records.

Runtime policy

Not every task needs a retained runtime. Prefer the cheapest safe runtime:

Runtime need	Use
Read platform state and summarize	No retained runtime
Call Akua API through tools	No retained runtime
Edit a repository or run tests	Retained filesystem
Run commands	Shell, usually approval-gated
Inspect a web app visually	Browser, usually disabled unless needed

Related topics

Ambient agents

Configure background triggers and policy.

Permissions and security

Choose safe grants and approval gates.