main.go

Overview

This file implements a simple example application that demonstrates how to create and run AI agents using the provided agent framework. It defines two custom sub-agents (myAgent), each generating greeting messages asynchronously. These sub-agents are composed into a single parallel agent that runs both sub-agents concurrently. The overall agent is then launched via a launcher infrastructure that handles execution lifecycle and command-line argument parsing.

The main purpose of the file is to illustrate:

How to define custom agents by implementing the Run method.
How to create and configure agents using the agent.New API.
How to compose multiple agents into a parallel agent using the parallelagent package.
How to launch the composed agent using the launch infrastructure (launcher and full).

Key Components

`main()` function

The entry point of the application. It performs the following steps:

Creates two sub-agents (subAgent1 and subAgent2) using the agent.New constructor:
- Each sub-agent is configured with a unique name, description, and a run function defined by myAgent{id: N}.Run.
- Errors during creation are handled by logging and terminating the program.
Creates a parallel agent (parallelAgent) using parallelagent.New:
- This agent runs the two sub-agents concurrently.
- The parallel agent itself is configured with a name, description, and the list of sub-agents.
- Again, any creation error causes a fatal log.
Prepares a launcher configuration with the parallel agent loaded through agent.NewSingleLoader.
Instantiates a full-featured launcher (full.NewLauncher) and executes it with the context and configuration:
- Passes command-line arguments (excluding the program name).
- If the launch fails, logs the error and the expected command-line syntax.

Parameters:

Uses the OS command-line arguments (os.Args) for launcher execution.

Usage:

go run main.go [launcher options]

`myAgent` struct and `Run` method

myAgent is a custom agent type defined with a single field:

type myAgent struct {
    id int
}

This field identifies the agent instance.

`Run` method

Signature:

func (a myAgent) Run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error]

Implements the core agent logic.
Returns an iterator function (iter.Seq2) that yields zero or more *session.Event objects and possible errors asynchronously.

Behavior:

Yields exactly 3 events.
Each event contains an LLM response with a greeting message including the agent's ID.
After each event is yielded, the method sleeps for a random duration between 1 and 5 seconds.
If the yield callback returns false (indicating the consumer is no longer interested), the iteration stops early.

Parameters:

ctx: Invocation context providing session info, cancellation, and utilities.

Return:

A function that takes a yield callback to send events/errors.
The events carry content of type genai.Content wrapping the greeting text.

Example event content:

Hello from MyAgent id: 1!

Usage:
The framework calls Run, which then asynchronously generates events for session consumption.

Implementation Details and Algorithms

The Run method uses a closure returning a generator-like function, enabling incremental event streaming.
Randomized delays simulate asynchronous or time-consuming processing between events.
The parallel agent runs multiple sub-agent Run methods concurrently, orchestrating their event streams without blocking each other.
The launcher infrastructure manages lifecycle, input parsing, and tying the agent execution to the CLI environment.

Interactions with Other System Components

Agent Framework (agent package): Provides abstractions for defining agents, configurations, and invocation contexts.
Session and Event Model (session, model): Events generated by agents conform to the session event model, allowing integration with broader session management and state persistence.
Parallel Agent (parallelagent package): Composes multiple agents into a parallel workflow, enabling concurrent execution and event merging.
Launcher (launcher, full packages): Handles agent loading, command-line interface, and execution orchestration.
LLM Content (genai package): Event payloads are structured as LLM responses compatible with the AI model integration.

The file acts as a top-level orchestrator that ties these components together to demonstrate a parallel-agent use case.

Diagram: Agent Structure and Execution Flow

flowchart TD
Main["main()"]
subAgent1["myAgent{id:1}\nRun()"]
subAgent2["myAgent{id:2}\nRun()"]
parallelAgent["parallelAgent\n(parallelagent)"]
launcher["Launcher\n(full)"]
Main --> subAgent1
Main --> subAgent2
subAgent1 --> parallelAgent
subAgent2 --> parallelAgent
parallelAgent --> launcher
launcher -->|Executes| parallelAgent

main() creates two myAgent instances.
Each agent has a Run() method generating events.
Both agents are composed into parallelAgent.
The launcher executes the parallelAgent and manages the lifecycle.

Summary of Public API Elements

Element	Type	Description
`main()`	`func()`	Entry point, creates agents and launches them.
`myAgent`	`struct`	Custom agent with an integer ID.
myAgent.Run	`func(agent.InvocationContext) iter.Seq2[*session.Event,error]`	Generates a sequence of greeting events asynchronously.

References

Agent Invocation Context — Context and lifecycle interfaces used in Run.
Parallel Agent — Parallel composition of sub-agents.
Agent Lifecycle and Callbacks — Execution hooks and event streaming.
Session Management — Session events and state management.
Launcher and Command Line — Launch infrastructure for running agents.
LLM Integration and Agents — Integration with large language models and event content structures.