Agents

Agents that deploy, investigate, and prepare reviewable changes with clear controls

Agents are workspace-native automation in Akua: describe the outcome, let the agent gather context, and review the proposed action before anything sensitive changes.

Work modes

The same configured agent can help in chat, investigate platform state, use code when needed, or run from a configured signal.

Chat

Ask the dashboard sidebar to deploy a repository, explain a failed install, compare customer deployments, or prepare a safe next step.

Investigate

Gather evidence from platform state, deployment data, logs, package versions, and existing repository change requests before deciding what to do.

Code

Use fast Code Mode for structured platform operations, then switch to a retained runtime when the task needs files, git, package managers, command execution, or tests.

Ambient

Watch configured signals and start an investigation when deploy failures, security findings, quota pressure, or customer-defined events match policy.

Agents are clients of the same Akua API used by the dashboard, CLI, and MCP server. That keeps behavior auditable and avoids separate automation paths.

Why agents matter

Agents turn deployment and operations work into a guided conversation. The embedded dashboard agent is the managed path: no local setup, shared workspace context, and review controls built into the UI.

Deploy by intent

Tell the agent what you want to run. It can identify setup steps, ask for missing configuration, and show deployment progress.

Review before change

Sensitive actions use repository change requests, approval requests, and audit events instead of invisible automation.

Match the user

Beginners get plain-language guidance. Experts get concise technical detail, exact resource names, and direct controls.

Use your own tools

Codex, Claude Code, and other MCP-compatible clients can connect through the Platform MCP server when teams prefer local workflows.

Product model

How agents work

Understand agents, skills, sessions, turns, events, and repository change requests.

Examples

See realistic deployment, investigation, compute recommendation, and ambient flows.

Agent API tasks

Create agents, sessions, turns, approvals, and repository change requests.

Communication style

Understand beginner, intermediate, advanced, and expert agent responses.

Configure an agent

Define instructions, skills, model policy, runtime policy, grants, and triggers.

Agent dashboard

Configure ambient agents and understand widgets in the managed UI.

Sessions and turns

See how a conversation or task progresses over time.

Ambient agents

Configure agents that respond to deploy failures, degraded clusters, findings, and other signals.

Permissions and security

Control what agents can read, prepare, execute, and accept.

Agents API

Build on the public API resources and SDK shape.

Limits and pricing

Understand agent sessions, retained runtimes, model budgets, and trigger limits.

Agent runbooks

Triage stuck sessions, sandboxes, provider outages, triggers, and cleanup.

When to use an agent

Use an agent when the work benefits from platform context, repeatability, or review:

Use case	Good fit
Explain a failed deployment	Read-only triage agent
Compare two installations	Chat or API-created session
Create a reviewable fix	Coding agent with repository change request access
Watch production failures	Ambient agent with deploy-failure triggers
Run a safe low-risk remediation	Agent with explicit pre-approved grants

For direct API exploration without a hosted session, use the Platform MCP server. For repository-focused design, see Agents and installation repositories.

Common questions

Do agents run all the time?

No. Sessions are cheap to keep open, but retained runtimes only start when work needs files, commands, a browser, or repository access. Ambient agents wait on configured signals until a condition matches.

Can agents accept changes directly?

The default path is a repository change request. Accepting a change requires separate grants and can require explicit approval at runtime.

Can I bring my own model keys?

Yes. Agents support Akua-managed billing and workspace-owned provider credentials through workspace secrets. Secret values are not exposed to the agent runtime.

What happens to retained filesystems?

Retained filesystems expire according to workspace policy unless pinned. Summaries, repository change requests, and audit events are cheaper to keep than full runtime state.

Related topics

Platform MCP

Let external AI tools call Akua through Code Mode.

Examples

See how hosted agents guide deployments, machine choices, and investigations.

Installation repositories

The git-backed deployment surface agents inspect and propose changes against.

Repository change requests

How agents use repositories and change requests for reviewable changes.

Agent limits

Pricing and limits for sessions, turns, retained runtimes, and provider usage.