Configuration

Agent Discovery

The ADK CLI automatically discovers agents in your project through intelligent file scanning.

Discovery Rules

• File Patterns: Recursively scans for agent.ts and agent.js files
• Excluded Directories: node_modules, .git, dist, build, .next, .turbo, coverage, .vscode, .idea
• Gitignore Support: Respects .gitignore patterns for additional exclusions
• Interactive Selection: Shows agent selector when multiple agents are found

Required Exports

The ADK CLI expects specific export patterns to recognize your agents. Each agent file must match one of the following patterns:

Option 1: Default Export (Most Common) Best for simple agents. Export an LlmAgent instance directly as the default export:

import { LlmAgent } from "@iqai/adk";

export default new LlmAgent({
  name: "my_agent",
  model: "gemini-2.5-flash",
  instruction: "You are a helpful assistant.",
});

Option 2: Named Function Export Recommended for complex agents that need initialization or configuration. Export an async function named agent:

import { AgentBuilder } from "@iqai/adk";

export async function agent() {
  return await AgentBuilder.create("my_agent")
    .withModel("gemini-2.5-flash")
    .withInstruction("You are a helpful assistant.")
    .build();
}

Option 3: Named Export Export a function or instance with the name agent:

export const agent = () =>
  new LlmAgent({
    name: "my_agent",
    model: "gemini-2.5-flash",
    instruction: "You are a helpful assistant.",
  });

Development Workflow

Package Manager Detection

When creating projects with adk new, the CLI auto-detects available package managers:

• 📦 npm
• ⚡ pnpm
• 🧶 yarn
• 🍞 bun

Troubleshooting

Common Issues

Agent not detected?

• Verify file naming: agent.ts or agent.js
• Check export format matches supported types
• Ensure agent isn't in excluded directories
• Review .gitignore patterns

Discovery issues?

• Use adk serve and check GET /api/agents endpoint
• Enable verbose logging with --verbose flag
• Verify TypeScript compilation if using .ts files

Module resolution errors?

• Ensure proper imports in your agent files
• Check that dependencies are installed
• Verify TypeScript configuration if using .ts files

Build or runtime errors?

• Check agent export patterns match required formats
• Verify environment variables are properly loaded
• Use debug logging for detailed error information

Hot reload not working?

• Check file watching permissions
• Review .gitignore patterns that might exclude files
• Ensure watched paths are correctly configured

Session or state issues?

• Verify session management in your agent implementation
• Check that state persistence is working correctly
• Use the API endpoints to debug session data

Debug Configuration

Enable detailed logging to diagnose issues:

# Enable debug logging
export ADK_DEBUG_NEST=true
export ADK_VERBOSE=true

# Run with verbose output
adk run --verbose
adk serve --verbose

Useful Debugging Commands

# Check discovered agents
adk serve
# Then visit http://localhost:8042/api/agents

# Test agent loading
adk run --verbose

# Check API endpoints
curl http://localhost:8042/health
curl http://localhost:8042/api/agents