What is an Agent in Yukkai?
Learn what an agent is in Yukkai, how sub-agents work in isolated conversations, and how they form the building blocks of Swarm orchestration.
In Yukkai, an agent is an autonomous AI worker that runs in its own isolated conversation. It has its own system prompt, tool access, and message history — completely separate from your main conversation. Agents are the fundamental building block that enables Yukkai to decompose complex work into parallel tasks.
How Agents Work
Each agent you launch operates as a fully independent AI session:
- Isolated context — The sub-agent has no access to your main conversation. It only sees the instructions you pass in its
prompt. This means every prompt must be fully self-contained. - Own tool access — Agents can use any of Yukkai's 39+ native tools (file operations, bash, browser, etc.), subject to the same security layers as the main session.
- Own message history — The agent maintains its own conversation thread internally, up to a limit of 50 messages.
- Role-based behaviour — When an agent is assigned a role (e.g., "Developer", "Researcher"), it inherits that role's system prompt and tool restrictions.
Launching a Single Agent
For a one-off parallel task, use the agent tool directly:
agent(prompt: "Read all files in src/utils and summarize their public API in one paragraph each.")This is the simplest way to delegate work. The agent runs in the background, uses tools as needed, and returns its result when done.
From Single Agents to Swarms
When you need many agents working in parallel on related tasks, you graduate from the agent tool to the Swarm system. A swarm is a coordinated plan of multiple agents, each with an assigned role and a specific task. See Swarm Overview for details.
Agent Limits and Safety
Every agent in Yukkai is bounded by a triple safety system:
| Limit | Value | Purpose |
|---|---|---|
| Inactivity timeout | 180 seconds | Kills agents stuck between tool calls |
| Overall timeout | 1,800 seconds (30 min) | Caps total execution time |
| Message limit | 50 messages | Prevents runaway conversations |
These limits ensure that even with dozens of agents running in parallel, no single agent can consume unbounded resources.
Key Principles
- Self-contained prompts — Never reference "the file we discussed" or rely on main-conversation context. Be fully explicit in every instruction.
- Role assignment — Pick a role that matches the task (Developer, Tester, Researcher, etc.) so the agent gets the right system prompt and tool restrictions.
- Atomic tasks — Decompose work so each agent handles one file, one module, or one clear aspect. Finer decomposition means more effective parallelism.