Create an AI Agent

This guide walks you through creating and deploying agents using the Agent Runtime Operator. Whether you’re building your first agent or exploring advanced patterns, this guide provides step-by-step instructions to get you up and running.

Before following this guide, make sure you have the Agent Runtime Operator installed. See Install the Agent Runtime Operator for installation instructions.

Quick Start: Your First Agent

Get your first agent running in under 5 minutes.

Deploy your first agent

Replace your-gemini-api-key-here with your actual Gemini API key before deploying. 
# Create a simple helpful assistant using templates
cat <<EOF | kubectl apply -f -
apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: Agent
metadata:
  name: my-first-agent
spec:
  framework: google-adk
  description: "A helpful AI assistant"
  instruction: "You are a helpful AI assistant that can answer questions, provide explanations, and help with various tasks. Be friendly, informative, and concise in your responses."
  model: "gemini/gemini-2.5-flash"
  protocols:
    - type: A2A
  replicas: 1
  env:
    - name: GEMINI_API_KEY
      value: "your-gemini-api-key-here"
EOF

Verify your agent is running

# Check the agent resource
kubectl get agent my-first-agent

# Check the deployment
kubectl get deployment my-first-agent

# Check the service
kubectl get service my-first-agent

Check the logs

# View agent logs
kubectl logs -l app=my-first-agent

🎉 Congratulations! You’ve successfully deployed your first agent.

Template-Based Agents (Recommended)

Template-based agents are the easiest way to get started. The operator handles the container image and runtime configuration for you.

When to use templates vs custom images

Use templates when:

  • You’re just getting started with agents

  • You want to quickly prototype agent behavior

  • You need standard agent capabilities with tools and sub-agents

  • You don’t need custom dependencies or specialized runtime environments

Use custom images when:

  • You have specific runtime requirements

  • You need custom dependencies or libraries

  • You want full control over the agent implementation

  • You’re migrating existing agent code

Step-by-Step: News Agent with Tools

Let’s create a more sophisticated news agent that uses external tools:

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: Agent
metadata:
  name: news-agent
spec:
  framework: google-adk
  description: "A news agent that fetches and summarizes current articles"
  instruction: "You are a news agent that can fetch current news articles and provide summaries. Use the news fetcher tool to get articles and provide concise summaries."
  model: "gemini/gemini-2.5-flash"

  # External tools the agent can use
  tools:
    # Reference to ToolServer in the same namespace (namespace field omitted)
    - name: news_fetcher
      toolServerRef:
        name: news_fetcher_toolserver
    - name: web_fetcher
      toolServerRef:
        name: web_fetch_toolserver

  # Sub-agents this agent can delegate to
  subAgents:
    - name: summarizer_agent
      url: "https://agents.example.com/summarizer-agent.json"

  protocols:
    - type: A2A
  replicas: 1

Configuration Options for Templates

Basic Configuration

  • description: Brief description of your agent’s purpose

  • instruction: Detailed system prompt defining the agent’s behavior

  • model: Language model to use (defaults to framework default if not specified)

Custom Image Agents

When you need full control over your agent’s implementation, use custom images.

When you need custom images

  • Custom runtime environments or dependencies

  • Specialized libraries or frameworks

  • Legacy agent code migration

  • Performance-critical implementations

Step-by-Step: Weather Agent

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: Agent
metadata:
  name: weather-agent
spec:
  framework: google-adk
  image: ghcr.io/agentic-layer/weather-agent:0.3.0
  protocols:
    - type: A2A
  replicas: 1
  env:
    - name: LOGLEVEL
      value: "INFO"

Building Custom Agents

For examples and guidance on building custom agent images:

Container Requirements

Your custom agent container must:

  1. Expose an HTTP server on the configured port

  2. Implement the A2A protocol specification

Agent-Specific Configuration

Protocols

All agents use the A2A (Agent-to-Agent) protocol for communication:

protocols:
  - type: A2A
    port: 8000  # Optional: defaults to framework default
    path: "/"   # Optional: defaults to root path

Framework Options

The configured framework determines the base image and runtime environment.

Currently supported:

  • google-adk: Google Agent Development Kit framework

spec:
  framework: google-adk  # Default framework

Additional frameworks will be supported in the future.

Create an Agentic Workforce

What is an agentic workforce?

An agentic workforce is a collection of agents that work together to handle complex tasks. Instead of managing individual agents, you define entry points and let the operator automatically discover all connected agents and their capabilities.

Key terms

  • entry-point agents serve as the initial contact points, and the operator automatically discovers all

  • transitive agents are sub-agents called by your entry-point agents

When to use an agentic workforce

Use agentic workforces when:

  • You have multiple agents that need to collaborate on tasks

  • You want centralized visibility into all agents and tools in a system

  • You need to track which agents can delegate to which other agents

  • You want to organize agents by business domain or use case

  • You need automatic discovery of agent dependencies and capabilities

Use individual agents when:

  • You have a single, standalone agent

  • Your agent doesn’t interact with other agents

  • You need simple, direct agent deployment

Deploy your first workforce

This example assumes you have already deployed the agents referenced as entry points. See the sections above for how to create agents. 
# Create a workforce that orchestrates multiple customer service agents
cat <<EOF | kubectl apply -f -
apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: AgenticWorkforce
metadata:
  name: customer-service-workforce
spec:
  # Human-readable name for the workforce
  name: "Customer Service Team"

  # Description of the workforce's purpose
  description: "A workforce handling customer inquiries, support tickets, and product recommendations"

  # Owner of the workforce (email or identifier)
  owner: "platform-team@example.com"

  # Optional tags for organization
  tags:
    - customer-service
    - support
    - production

  # Entry point agents - the initial agents users interact with
  # The operator discovers all transitive agents (sub-agents) automatically
  entryPointAgents:
    # Agent in the same namespace
    - name: my-first-agent

    # Agent in a different namespace (optional)
    # - name: specialist-agent
    #   namespace: ai-agents
EOF

Verify your workforce is running

# Check the workforce resource
kubectl get agenticworkforce customer-service-workforce

# View detailed status including discovered agents and tools
kubectl describe agenticworkforce customer-service-workforce

# Check discovered transitive agents
kubectl get agenticworkforce customer-service-workforce -o jsonpath='{.status.transitiveAgents[*].name}'

# Check discovered transitive tools
kubectl get agenticworkforce customer-service-workforce -o jsonpath='{.status.transitiveTools[*]}'

Understanding workforce discovery

The operator automatically analyzes your entry-point agents to discover:

  • Transitive agents: All sub-agents that your entry points can delegate to (both in-cluster and remote)

  • Transitive tools: All tools available across the entire workforce

This information appears in the workforce’s status, giving you complete visibility into your agent ecosystem.

🎉 Congratulations! You’ve successfully created your first agentic workforce.

Happy agent building! 🤖