convez.ai
MCP ServerIntegração & APIsAvançado
ai-mpathyminds

YAAgents

ai-mpathyminds/yaagents

APIs REST governadas para agentes de IA em produção

Ver no GitHub
BomPluginScore · de 0 a 100

Gateway e SDKs para expor agentes de IA através de APIs REST governadas em produção. Mantém a flexibilidade da implementação do agente enquanto adiciona autenticação, contexto de tenant, auditoria, respostas tipadas e contratos OpenAPI no nível do gateway.

Instalação

$npx convez-ai ai-mpathyminds/yaagents

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 2 meses
Versão
—
Issues abertas
18
Contribuidores
2

Casos de uso

  • Expor agentes de IA através de APIs REST com autenticação e auditoria
  • Implementar fluxos de aprovação e esclarecimento em sistemas com agentes
  • Integrar agentes em arquiteturas existentes com RBAC e contexto de tenant

Veredito

YAAgents é uma solução sólida para quem precisa colocar agentes de IA em produção respeitando disciplina de API (autenticação, auditoria, tipagem). Recomendado para arquiteturas enterprise que já têm gateway patterns consolidados.

README

A tradução para o português deste README ainda está na fila.

YAAgents

License: Apache 2.0 Go 1.22+ Python 3.11+ CI Gateway image Profile version

You're building an AI agent that needs to live behind a normal REST API — with auth, tenancy, audit, typed responses, and OpenAPI. YAAgents is the gateway + SDKs that let you keep your agent framework and still ship a governed product API.

v0.4 work in progress. Plugins (token-validator, tenant-injector, license-check, prompt-sanitize, otel-audit) are now Stable. Published artifacts are v0.3.0; v0.4.0 ships in PI5-yaa alongside the Helm chart and full publish wave.


What problem does yaagents solve?

Most production systems already have REST APIs, OpenAPI contracts, gateways, RBAC, audit logs, tenant context, rate limits, and SDKs.

AI agents often bypass that discipline through chat interfaces, generic invoke endpoints, or framework-specific runtimes.

yaagents keeps the agent implementation flexible, but exposes it through normal business APIs:

  • resource-oriented endpoints
  • typed outcomes
  • clarification and approval responses
  • gateway-level auth, tenant context, audit, and policy
  • framework-neutral agent implementation

See also: Why Agentic REST? and Comparisons on the docs site.


What you can build

Here's a product-recommendation API that asks for clarification when it has nothing to recommend.

EndpointAgentic response type
POST /recommendations/{customerId}clarification_required — no purchase history to anchor on
POST /campaigns/{id}/optimizationssuccess — typed optimization result
POST /claims/{id}/reviewsapproval_required — high-risk claim needs human sign-off
HTTP/1.1 400 Bad Request
Content-Type: application/vnd.yaagents.clarification+json

{
  "type": "clarification_required",
  "requiredInputs": [
    {
      "name": "purchase_history",
      "question": "No purchase history for this customer. What items should anchor recommendations?"
    }
  ],
  "trace": { "correlationId": "corr-1", "requestId": "req-1" }
}

Run it: examples/store/ (Python) · examples/store-go/ (Go)


How it works

flowchart LR
  A["Application\n(any client)"] --> B["YAAgents Gateway\n(auth · tenant · audit)"]
  B --> C["Agentic API Service\n(your code)"]
  C --> D["Agent Implementation\n(your choice)"]
  D --> E["Optional: A2A / MCP / Tools"]

E-commerce recommendations — 7 steps:

  1. A product catalog service receives POST /recommendations/{customerId} requests.
  2. The yaagents gateway authenticates the request (token-validator plugin).
  3. The gateway injects tenant context (tenant-injector plugin).
  4. The backend Python service (using sdk-fastapi) runs recommendation logic.
  5. If the recommendation engine needs clarification (e.g., no purchase history), it returns clarification_required.
  6. The Go client (using sdk-go) handles clarification_required natively — no raw HTTP parsing.
  7. The audit log (otel-audit plugin) records the operation for every request.

Response Profile — YAAgents follows the Agentic REST Response Profile v0.3.

Response typeHTTP statusContent-Type
success200application/json
created201application/json
accepted202application/vnd.yaagents.operation+json
clarification_required400application/vnd.yaagents.clarification+json
validation_failed422application/vnd.yaagents.validation-error+json
approval_required412application/vnd.yaagents.approval-required+json
forbidden403application/vnd.yaagents.error+json
conflict409application/vnd.yaagents.conflict+json
failed_dependency424application/vnd.yaagents.error+json
error500application/vnd.yaagents.error+json

See the full normative spec for the mandatory trace block contract and per-type body shapes.


Who uses it

You areWhy YAAgentsStart here
A SaaS product team adding AI featuresKeep your existing API surface; add agentic operations as new resource endpoints.examples/store/
A platform team governing many agent servicesOne gateway for auth, tenancy, audit, and license — your agent services stay simple.Plugin docs
An API architect designing an agent productTyped outcomes, OpenAPI-first contracts, generated clients. No free-form text parsing.spec/agentic-rest-profile.md

See also: YAAgents vs A2A, AGNTCY, MCP, and frameworks — what each layer is for and where yaagents fits.


Get started

# Python SDK + client + CLI
pip install yaagents-fastapi yaagents-client yaagents-cli

# TypeScript / Node client
npm install @aimpathyminds/yaagents-client

# Go server SDK
go get github.com/ai-mpathyminds/yaagents-sdk-go

# Go client SDK
go get github.com/ai-mpathyminds/yaagents-client-go

# Gateway container image
docker pull ghcr.io/ai-mpathyminds/yaagents-gateway:0.3.0

Repository layout

yaagents/
├── spec/                    ← Agentic REST Response Profile (normative)
├── schemas/                 ← JSON schemas for all response types
├── openapi/                 ← Reusable OpenAPI components
├── docs/                    ← Pages site source (Astro Starlight)
├── gateway/                 ← Go gateway source                     [submodule]
├── sdk-fastapi/             ← Python FastAPI server SDK (yaagents-fastapi) [submodule]
├── sdk-go/                  ← Go server SDK (yaagents-sdk-go)       [submodule]
├── client-python/           ← Python client (yaagents-client)       [submodule]
├── client-ts/               ← TypeScript client (@aimpathyminds/yaagents-client) [submodule]
├── client-go/               ← Go client SDK (yaagents-client-go)    [submodule]
├── cli/                     ← CLI validator (yaagents-cli)           [submodule]
└── examples/                ← Reference examples + Docker Compose demos

Contributing

See CONTRIBUTING.md.


License

Apache 2.0 — see LICENSE. Published artifacts are v0.3.0; Profile v0.3. v0.1.x packages shipped under the previous source-available license remain under that license (non-retroactive). Contact bhaskar@aimpathyminds.com for historical v0.1.x license questions.


Security

See SECURITY.md for our responsible-disclosure policy.


Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

Ver o original no GitHub

Bom para

Relacionados