---
name: uru-agents
description: Create, inspect, and change Uru Agents and their Library resources. Use for Agent identity, instructions, behavior, tools, access, or attached knowledge.
---

# Uru Agents

An Uru Agent is a durable collaborator with scoped instructions, knowledge,
tools, and access.

Some tool fields still use `persona`. Treat that word as an internal name.
Use `Agent` in user-facing text.

## Workflow

1. Search with `library_query` and `resource_type="persona"`.
2. Read the Agent and its linked resources.
3. Create or change only the fields required by the request.
4. Read the result after a material change.
5. Report the Agent path and the changed fields.

Use `library_query` for Agent search, read, and linked-resource inspection. Use
`library_fs` for file-first creation, patches, and full JSON edits.

## Create an Agent

Create Agents as JSON-backed Library resources. Use a visible `.md` Library
path. The server stores the typed Agent resource behind that path.

```json
{
  "op": "write",
  "path": "library/Agents/Finance Analyst.md",
  "create": true,
  "content": "{\"identity\":{\"name\":\"Finance Analyst\",\"role\":\"Financial analyst\",\"purpose\":\"Review forecasts and explain material variance\",\"system_prompt\":\"Use exact figures and name each source.\"},\"knowledge\":{\"facts\":\"\"},\"behavior\":{\"communication_style\":\"professional\",\"rules_always\":[\"Show the source for material figures\"],\"rules_never\":[\"Invent a missing figure\"]},\"tools\":{},\"access\":{\"is_public\":false},\"scope\":\"workspace\",\"status\":\"draft\"}"
}
```

Keep the Agent focused. Give it:

- one clear job;
- specific output standards;
- short rules that can be tested;
- only the tools and Library resources it needs;
- a clear scope and status.

Do not tell an external assistant to claim the Agent's human identity or sign
as that Agent. The Uru runtime decides how an active Agent affects a session.

## Change an Agent

Read the Agent JSON first. Preserve fields that the request does not change.

For a small change, preview a patch with `library_query`, then apply it with
`library_fs`. You can update identity, system prompt, knowledge, behavior,
tools, access, scope, or status.

Use resource slugs or Library paths returned by Uru. Do not invent internal
UUIDs.

## Attach Library resources

An Agent can link to Context, Prompts, Datasets, files, Gems, and other
supported Library items.

- Context is the only automatic retrieval source.
- Other linked items form a compact inventory.
- The Agent must read or query inventory items through tools.
- Base Agent links can take part in Agent-share cascade rules.
- Private overlay links apply only to that viewer.
- Collection membership does not attach an item to an Agent.

Inspect the Agent with:

```json
{
  "op": "read",
  "path": "library/Agents/Finance Analyst.md"
}
```

Use the linked-resource fields in the returned JSON. Do not invent a field
name. Preserve unrelated links when you add or remove one.

Read `uru-context` for Context quality. Read `uru-library` for links, sharing,
Collections, comments, labels, and versions.

## Scope and teams

Use workspace scope for a shared Agent. Use personal scope for a private Agent.
Use `list_workspace_teams` before a team assignment.

Sharing an Agent can also share the base resources it depends on. Inspect the
Agent attachments before a broad share.

## Stop rules

- Do not use the old standalone Persona CRUD flow when the Library path works.
- Do not replace an Agent JSON object without reading it.
- Do not put secret values in Agent content or tool configuration.
- Do not promise retrieval for non-Context attachments.
- Do not expand access beyond the user's request.
- Stop after a conflict. Read the current Agent before you retry.