---
search:
  tags:
    - AI
    - GET
seo:
  description: >-
    Fetch an agent by its (org_id, name) handle. Reference for the GET
    /v1/ai/agents/name/{name} endpoint in the Roboto REST API.
sidebar:
  label: Get agent by name
  badge: GET
title: Get agent by name
type: openapi-operation
---
Fetch an agent by its ``(org_id, name)`` handle.

Mirrors :meth:`Action.from_name`: name + owning org are jointly unique
(enforced by the ``agents_unique_org_name`` constraint from chats_018),
so a name plus the resource-owner org always addresses at most one
agent. The dedicated ``/name/`` subpath avoids collision with
``/agents/<agent_id>`` for agent ids that happen to look like names.
Unlike :func:`get_agent` (which derives the org from the looked-up
record), name lookup needs the org up-front, so it goes through the
``X-Roboto-Resource-Owner-Id`` header via ``REQUIRES_OWNER_ORG``.

Agent names are free text, so the path segment arrives percent-encoded
and has to be decoded before it can match a stored name. API Gateway
hands the proxy path through verbatim -- without this, an agent named
"Food Preference User Triage" is looked up as
``Food%20Preference%20User%20Triage`` and always 404s.

### Access control
 - requires_resource_owner
 - Restricted tokens need the API scope `api.everything_else`

`GET /v1/ai/agents/name/{name}`