> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Ask the dashboard sidebar to deploy a repository, explain a failed install, compare customer installs, or prepare a safe next step.
Gather evidence from platform state, install status, logs, package versions, and existing repository change requests before deciding what to do.
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.
Watch configured signals and start an investigation when deploy failures, security findings, quota pressure, or cost anomalies 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.
Tell the agent what you want to run. It can identify setup steps, ask for missing configuration, and show deployment progress.
Sensitive actions use repository change requests, approval requests, and audit events instead of invisible automation.
Beginners get plain-language guidance. Experts get concise technical detail, exact resource names, and direct controls.
Codex, Claude Code, and other MCP-compatible clients can connect through the agent setup path.
## Product model
Understand agents, skills, sessions, turns, events, and repository change requests.
See realistic deployment, investigation, compute recommendation, and ambient flows.
Create agents, sessions, turns, approvals, and repository change requests.
Understand beginner, intermediate, advanced, and expert agent responses.
Define instructions, skills, model policy, runtime policy, grants, and triggers.
Configure ambient agents and understand widgets in the managed UI.
See how a conversation or task progresses over time.
Configure agents that respond to deploy failures, degraded clusters, findings, and other signals.
Control what agents can read, prepare, execute, and accept.
Build on the public API resources and SDK shape.
Understand agent sessions, retained runtimes, model budgets, and trigger limits.
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 installation | 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 |
To connect a local coding agent, start with [Agent Setup](/agent-setup). For direct API exploration without a hosted session, use the [Platform MCP server](/ai/platform-mcp). For repository-focused design, see [Agents and installation repositories](/ai/repo-agents).
## Common questions
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.
The default path is a repository change request. Accepting a change requires separate grants and can require explicit approval at runtime.
Yes. Agents support Akua-managed billing and workspace-owned provider credentials through workspace secrets. Secret values are not exposed to the agent runtime.
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
Connect local coding agents to Akua.
Let external AI tools call Akua through Code Mode.
The git-backed installation surface agents inspect and propose changes against.
Pricing and limits for sessions, turns, retained runtimes, and provider usage.