> ## 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.
# How agents work
> The resource model behind Akua agents, sessions, turns, events, skills, and repository change requests
An agent is a configured identity in a workspace. It has instructions, skills, policies, grants, and optional ambient triggers. You can use the same agent from the dashboard, API, or an automated signal.
The important distinction is between the long-lived agent configuration and the work it performs.
## Dashboard-native guidance
In the dashboard, an agent is more than a text box. It can behave like an interactive guide for deployment and operations work:
* Ask clarifying questions when a request is ambiguous.
* Render approval prompts before sensitive actions.
* Show deployment progress, status cards, documentation cards, and code blocks inline.
* Link or navigate to the right dashboard page when a visual workflow is better than chat.
* Adjust its language to the user's experience level.
This lets a user describe intent, such as "deploy my app", while the agent turns that intent into structured platform actions and reviewable decisions.
## Core resources
| Resource | What it represents |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Agent** | The configured identity: name, instructions, skills, capabilities, policies, and grants. |
| **Skill** | A versioned behavior module that teaches an agent how to perform a class of work. |
| **Session** | A durable conversation or task thread for one agent in one workspace. |
| **Turn** | One submitted instruction and its result. |
| **Event** | A normalized stream entry: message, progress update, widget, runtime lifecycle, artifact, handoff summary, or cancellation. |
| **Approval request** | A human approval gate for actions that need review. |
Sessions are cheap to keep open. Runtime environments are only used when a task needs files, a shell, a browser, git, package managers, or long-running command execution.
## Agents are not tied to one runner
The API describes what an agent is allowed to do, not which internal runner executes it. A read-only triage agent might only call platform tools. A coding agent might use a retained workspace with repository access, command execution, package managers, and test tooling.
This keeps the public contract stable as the runtime improves.
For platform operations, agents should prefer fast structured API work. For tasks that need files, repositories, scripts, package managers, browsers, or state between turns, they can use a retained runtime. Users see one conversation either way.
## Repository change requests are the review surface
When an agent needs to change repository-backed installation source or configuration, the default path is a [repository change request](/installs/repository-change-requests). The agent reads existing change requests in the workspace, checks whether work is already in progress, and creates a new request only when needed.
This prevents duplicate work and keeps production changes reviewable. Repository change request access is controlled by grants, and accepting a change can require a separate approval request. Read access does not imply permission to accept a change.
## Sessions produce events
Every turn emits events that the dashboard and API can display:
* Messages from the user, system, or assistant.
* Progress updates for platform, git, shell, browser, or repository work.
* Interactive UI outputs such as approval cards, status cards, forms, or documentation cards.
* Runtime start, stop, and resume events.
* Artifacts such as repository change requests, diffs, summaries, logs, or files.
* Handoff summaries and cancellation events.
The event stream is the source for chat replay, audit views, and external integrations.
## Related topics
Follow the lifecycle of a task.
See how agent sessions feel in deployment and operations workflows.
Understand grants, approvals, and workspace isolation.
See how agents adapt explanations to different users.