> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmable Agents FAQ

> Slugs, names, where agents live, and what to do when an agent is not found.

## Naming and finding agents

<AccordionGroup>
  <Accordion title="What do I pass as the agent, its name or its slug?">
    Either works. Paradime looks the agent up by slug first, then by name, case-insensitively.

    * **The name** is what you see in **Agent** → **Agents**, so it is usually the easier one to use.
    * **The slug** is in the agent's URL. Open the agent and the address reads `/agent/builder/edit/<slug>?uuid=…`; the path segment is the slug.

    Do not try to derive the slug from the name. It is truncated and carries a random suffix, so an agent called *DinoAI PR Review* might be `dinoai-pr-re-18cda0`. Copy it from the URL, or just use the name.

    The slug is minted once and never changes, which makes it the safer reference in anything long-lived.

    For an agent written as YAML, the name, the slug and the file name under `.dinoai/agents/` are all the same string, and the agent refuses to run if its `name:` field disagrees with its file name.
  </Accordion>

  <Accordion title="Where do agents live?">
    In one of two places, and both work everywhere an agent can be named:

    * **Built in the app** — deployed with **Just here**, the agent is saved to the workspace and is live immediately. There is no file in your repository.
    * **Written as YAML** — committed to `.dinoai/agents/` on your repository's **default branch**, either by hand or by deploying from the builder with **Open a pull request**.

    When both exist for the same reference, the workspace copy wins; the repository is the fallback.
  </Accordion>

  <Accordion title="Why are YAML agents read from the default branch?">
    So that a branch cannot change the agent that acts on it. For a reviewing agent this is the whole point: a pull request cannot rewrite its own reviewer to be lenient. An agent that exists only on a feature branch is invisible to a run.
  </Accordion>

  <Accordion title="I renamed the agent. Do I need to update anything?">
    The slug does not change, so anything referring to the agent by slug keeps working. If you refer to it by name — in a schedule, an API call or a GitHub workflow — update the reference to the new name, or switch it to the slug so it cannot drift again.
  </Accordion>

  <Accordion title="Can agent names be nested?">
    Yes, for YAML agents. One at `.dinoai/agents/team-a/pr-reviewer.yml` is referred to as `team-a/pr-reviewer`, and that whole path is what you pass. Useful when several teams keep agents in one repository.
  </Accordion>

  <Accordion title="My run says the agent could not be found.">
    Three things to check:

    1. **The reference matches.** Compare it against the agent's name in **Agent** → **Agents**. Names are matched case-insensitively, but not fuzzily.
    2. **It is deployed.** An agent still in the builder, or a YAML agent that only exists on a feature branch, is not visible to a run.
    3. **Two agents share a name.** An ambiguous name fails rather than picking one, and the error names the slugs so you can pass one of those instead.

    Callers differ in what happens next: the DinoAI GitHub Action reviews with its built-in reviewer when you have named no agent at all, but a name that resolves to nothing fails the run rather than quietly substituting something else.
  </Accordion>
</AccordionGroup>

## Running agents

<AccordionGroup>
  <Accordion title="Can one agent run against several workspaces or repositories?">
    An agent definition belongs to the repository it lives in, and a run belongs to one workspace. With an [account API key](/developers/api-keys) you can trigger runs across workspaces with a single key by naming the target workspace per request, but each workspace resolves the agent from its own repository.
  </Accordion>

  <Accordion title="Which commit does an agent work on?">
    Whatever you pass as `base_branch`: a branch, a tag or a commit SHA. It defaults to the repository's default branch. Passing an exact commit pins the run to that tree, which is how the GitHub Action reviews precisely the commit under review rather than wherever the branch has moved to.
  </Accordion>

  <Accordion title="How do I limit what an agent can do?">
    With the `tools` allowlist — see the [Tools Reference](/products/dino-ai/programmable-agents/tools-reference). If the `tools` block is omitted the agent has every tool. An allowlist is worth it for agents that run unattended, and read-only agents such as reviewers are the obvious case.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quick start" icon="rocket" href="/products/dino-ai/programmable-agents/quick-start">
    Build and run your first agent.
  </Card>

  <Card title="YAML configuration" icon="file-code" href="/products/dino-ai/programmable-agents/yaml-configuration">
    Every field a definition supports.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/products/dino-ai/programmable-agents/tools-reference">
    What each tool does.
  </Card>

  <Card title="Agent sessions" icon="list-check" href="/products/dino-ai/programmable-agents/agent-sessions">
    Track and debug runs.
  </Card>
</CardGroup>


## Related topics

- [PR reviewer with the DinoAI GitHub Action](/guides/programmable-agents/github-action-pr-reviewer.md)
- [Programmable Agents](/products/dino-ai/programmable-agents/index.md)
- [Programmable Agents quick start](/products/dino-ai/programmable-agents/quick-start.md)
- [DinoAI Programmable Agents](/developers/python-sdk/modules/dinoai-programmable-agents.md)
- [DinoAI Programmable Agents API](/developers/graphql-api/api-reference/dinoai-programmable-agents-api.md)