Single Agent

---
name: single-agent
description: "Guide one Swarms Agent, its memory, skills, marketplace, prompt
  caching, and support objects."
metadata:
  disco-role: operating
disable-model-invocation: true
license: Apache 2.0
---

# Single Agent

Use this sub-skill when the user wants to create, configure, inspect, or debug one Swarms `Agent` and the objects that travel with it.

## Owns these workflows

- Build a new `Agent` with the right model, loop count, tools, and output type.
- Attach skills from a `skills_dir` and decide when to load them statically or dynamically.
- Turn on or tune memory, context compression, fallback models, streaming, prompt caching, and multimodal input.
- Load or publish marketplace prompts.
- Work with the support objects that make a single agent usable: `Conversation`, `Artifact`, `SkillsManager`, `ContextCompressor`, `LLMManager`, and `AgentMarketplaceHandler`.

## Does not own

- CLI command parsing or YAML/markdown file loaders; use `cli-loaders` for those.
- Tool schema conversion, BaseTool, or MCP server/client details; use `tools-mcp`.
- Multi-agent orchestration, routing, debate, group chat, or swarm planning; use `multi-agent-workflows`.

## Read this sub-skill when the request mentions

- `Agent`, `run`, `run_stream`, `max_loops`, `interactive`, `autosave`, or `output_type`.
- `skills_dir`, `SkillsManager`, `persistent_memory`, `context_compression`, or `WORKSPACE_DIR`.
- `marketplace_prompt_id`, `SWARMS_API_KEY`, or prompt marketplace workflows.
- `prompt_caching`, `cache_config`, model fallback, or provider-specific parameter behavior.
- `Conversation`, `Artifact`, `add_memory`, or state save/load issues.

## Working shape

1. Decide whether the task is a minimal agent, a skills-enabled agent, a memory-backed agent, or a provider-specific live run.
2. Check the user’s model, key, and workspace assumptions before recommending runtime settings.
3. Prefer a minimal offline smoke check first; only move to live provider execution if the user has keys and wants a real model call.
4. Use the bundled references for constructor knobs, workflow examples, and failure recovery.

## What to read next

- `references/api-reference.md` for the confirmed `Agent` signature and the main support-object APIs.
- `references/workflows.md` for common single-agent recipes.
- `references/troubleshooting.md` for workspace, key, fallback, and marketplace failures.
- `scripts/agent_smoke.py` for a local offline import and support-object check.

## Typical user questions this sub-skill should answer

- How do I create one agent that remembers state across runs?
- How do I load a skill folder or choose relevant skills for a task?
- Why is my agent not writing memory files where I expect?
- Why did a prompt-caching or provider call fail even though the agent built successfully?
- How do I attach a marketplace prompt without hand-editing the system prompt?

## Route boundaries

- If the task starts with a command such as `swarms agent` or `swarms setup-check`, route to `cli-loaders`.
- If the user is really asking for a workflow of multiple agents, route to `multi-agent-workflows`.
- If the user is mainly converting functions to tools or attaching MCP, route to `tools-mcp`.

## Acceptance checklist

- The response should name the relevant `Agent` fields and support objects.
- The answer should mention any required env vars or workspace assumptions.
- The answer should give a concrete recovery path for missing keys, missing workspace, or invalid skill directories.
- If live execution is requested, the answer should say which provider credentials are required before a model call can succeed.