You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Agent-focused reference for working with the Genkit-based multi-agent system (flows, agents, tools, prompts, MCP, A2A).
AGENTS.md
This file is a machine- and agent-oriented guide for contributors and automated coding agents working on Genkit-UI. It focuses on actionable commands, architecture, and operational details agents need to inspect, test, and modify the codebase.
Project Overview
Genkit-UI is a TypeScript multi-agent system built on Google Genkit and the A2A (Agent-to-Agent) protocol for complex tasks like research, code generation, and content creation.
Architecture
The system orchestrates specialized agents through Genkit flows and A2A communication:
Genkit Flows (src/flows): High-level orchestrations with Zod schemas for input/output validation.
Config (src/config.ts): Central Genkit ai instance with Gemini 2.5 Flash model.
MCP (src/mcp): Model Context Protocol utilities for tool registry and context propagation.
Data Flow
graph TD
A[User Query] --> B[Orchestrator Flow]
B --> C{A2A Protocol}
C --> D[Planning Agent]
C --> E[Coder Agent]
C --> F[Research Agents]
C --> G[Content Editor Agent]
C --> H[Data Analysis Agent]
D --> I[Tools/APIs]
E --> I
F --> I
G --> I
H --> I
I --> J[Aggregate Results]
J --> B
B --> K[Final Response]
subgraph "Genkit Flows"
B
end
subgraph "A2A Agents"
D
E
F
G
H
end
subgraph "Tools & APIs"
I
end
Set environment variables: GEMINI_API_KEY required (mandatory), optionally SERPAPI_API_KEY, NEWSAPI_API_KEY, VECTORSTORE_INDEX.
Verify setup: npm run genkit:ui (starts dev UI for flows/tools).
Development Workflow
Start Genkit UI (flows/tools testing): npm run genkit:ui – watches src/index.ts, serves at localhost:3000.
Start local flow server (HTTP): npm run flow:serve (port: env FLOW_PORT or 3400).
Start individual agent servers: e.g. npm run agents:orchestrator (port 41243), npm run agents:planning (port 41244), npm run agents:academic (41245), npm run agents:news (41246), npm run agents:data-analysis (41247), npm run agents:coder (41242), npm run agents:content-editor (10003), npm run agents:web-research (41248).
Interact with agents: npm run a2a:cli http://localhost:41243 (example for orchestrator) – streams messages, handles tasks/sessions.
Hot reload: tsx watches TS files; restart agents for prompt/config changes.
Debug: Enable thinkingConfig.showThoughts: true in src/config.ts for Gemini traces; use Genkit UI for flow visualization.
Testing Instructions
Local mocking conventions: Use vi.mock to mock Genkit ai, A2A eventBus, external APIs (wikipedia, weather).
Add tests: For new code, add to __tests__/ with describe/it/expect; mock dependencies to isolate units.
Code Style Guidelines
TypeScript: Strict mode (tsconfig.json); use interfaces for A2A types (src/agents/shared/interfaces.ts). Async/await over promises; type all functions.
Genkit patterns: ai.defineFlow/ai.defineTool with Zod schemas (inputSchema/outputSchema); import ai from ../config.js.
A2A agents: index.ts sets up Express + A2AExpressApp; implement AgentExecutor with execute(requestContext, eventBus); publish Task/Status events.
Naming: camelCase for vars/functions, PascalCase for classes/interfaces. Prompts in .prompt files next to agents.
Imports: Relative for local (../config), absolute for node_modules. No unused imports (ESLint).
Error handling: Try-catch in executors; throw descriptive errors in tools; publish failed status.
Linting/Formatting: ESLint (eslint.config.js) for TS rules; Prettier (prettier.config.js) for formatting. Run npm run lint -- --fix before commit.
Build and Deployment
No build step: Direct TS execution via tsx (npm scripts use tsx src/...).
Production: Set NODE_ENV=production; use PM2/forever for agent servers. Docker: Use docker-compose.yaml for multi-agent stack (env vars injected).
Firebase App Hosting: For serverless deployment, use firebase deploy --only hosting:apphosting to deploy the backend (genkit-backend). Adapts agents/flows as callable endpoints (e.g., /orchestrator). Set secrets with firebase functions:secrets:set GEMINI_API_KEY. Local test: firebase emulators:start --only functions,hosting. See firebase.json for config.
CI/CD: GitHub Actions (.github/workflows/); run tests/lint on PRs. For agents, test A2A endpoints with mocks.
Security Considerations
API Keys: Never commit keys; use .env (gitignore'd). Agents check GEMINI_API_KEY at startup.
A2A: Localhost by default; add auth (securitySchemes in AgentCard) for production. Validate inputs to prevent injection in prompts/tools.
Tools: Wikipedia public but rate-limit; weather mock—use secure API in prod. No user data persistence.
Pull Request Guidelines
Title format: [agent/flow/tool] Short description (e.g., [orchestrator-agent] Improve task delegation).
Required checks: npm test, npm run lint (if configured in CI). Fix type and lint errors before merging.
When changing prompts or schemas, include a small unit test that verifies behavior or adds examples to src/flows.
For agent or A2A changes, include updates to the relevant AgentCard and add integration tests for A2A message flows if possible.
Debugging and Troubleshooting
Agent won't start: verify GEMINI_API_KEY and PORT overrides.
Flow not registered in UI: ensure src/index.ts exports the flow and restart the Genkit UI/FlowServer.
Mismatched Zod schemas: update flows and add tests; most flows validate input using Zod at runtime.