main.go

Overview

The main.go file serves as the entry point for an application that demonstrates the creation and orchestration of AI agents using a sequential workflow. It defines custom agents that generate simple greeting responses and composes them into a sequential agent that runs these sub-agents in order. The program then launches the composed agent using a full-featured launcher, handling command-line arguments and runtime execution.

The primary functionality revolves around:

• Defining a custom agent type with a greeting response.

• Creating individual agent instances with unique identifiers.

• Combining these agents into a sequential workflow agent.

• Launching the composed agent via a launcher interface to handle invocation and execution lifecycle.

This file heavily interacts with the agent framework, sequential workflow agents, session event streaming, and launcher components.

Detailed Explanations

Type: myAgent

type myAgent struct {
	id int
}

• Purpose: Represents a simple custom agent with an identifier.

• Fields:

  • id (int): Unique identifier to distinguish agent instances.

Method: Run

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

• Purpose: Implements the agent's behavior when invoked.

• Parameters:

  • ctx (agent.InvocationContext): Provides invocation context, including session, memory, and artifact access.

• Returns: A sequence generator function iter.Seq2[*session.Event, error] that yields session events or errors.

• Behavior:

  • The returned function yields a single session.Event containing an LLM response.

  • The LLM response's content includes a greeting message with the agent's id.

• Usage Example:

a := myAgent{id: 1}
eventSeq := a.Run(ctx)
eventSeq(func(ev *session.Event, err error) bool {
    if err != nil {
        // handle error
        return false
    }
    fmt.Println(ev.LLMResponse.Content.Parts[0].Text)
    return true
})

This method demonstrates the use of the iterator pattern to asynchronously produce events during agent execution, consistent with the framework's event-driven design.

Function: main

func main()

• Purpose: Orchestrates the instantiation and execution of the agents and the launcher.

• Workflow:

  1. Context Creation: Initializes a background context ctx.

  2. Agent Creation:

     • Creates two instances of myAgent as agent.Agent objects with different IDs (1 and 2).

     • Uses agent.New() with a configuration specifying the agent's name, description, and run function.

     • Handles errors during agent creation by logging fatal messages.

  3. Sequential Agent Creation:

     • Creates a sequentialagent.Agent named "sequential_agent".

     • Configures it with the two previously created agents as sub-agents.

  4. Launcher Configuration:

     • Sets up a launcher.Config using a single-agent loader for the sequential agent.

     • Instantiates a full launcher with full.NewLauncher().

  5. Agent Execution:

     • Executes the launcher passing the context, configuration, and command-line arguments.

     • Logs fatal errors and command-line usage if execution fails.

• Interactions:

  • Uses the agent package to create agents.

  • Uses sequentialagent package to create a workflow agent.

  • Uses launcher and full packages to handle lifecycle and command-line execution.

• Error Handling: Fatal logs terminate the application if agent creation or execution fails.

Important Implementation Details and Algorithms

• Agent Execution as Event Streams: Agents implement a Run method returning an iterator function iter.Seq2 that yields zero or more session.Event objects asynchronously, allowing streaming results.

• Sequential Agent Workflow: The sequentialagent composes multiple agents and runs them one after the other, collecting their outputs in sequence. This enables pipeline-style workflows.

• Agent Configuration: Agents are configured via agent.Config structs, specifying name, description, and run logic, supporting modular and reusable agent definitions.

• Launcher Integration: The launcher system abstracts process startup, argument parsing, and runtime execution, enabling flexible launching modes and command-line interactions.

• Event Structure: The yielded session.Event contains an LLM response with nested content and parts, utilizing the genai.Content and genai.Part structures to represent textual output.

Interactions with Other System Components

• Agent Framework (agent package): Provides core abstractions for creating and running agents, managing invocation context and event streams.

• Sequential Agent (sequentialagent package): Manages execution of multiple agents in order, useful for building complex workflows.

• Session Events (session package): Defines event types for communication between agents and the session manager.

• GenAI Content (genai package): Structures the LLM response content parts, enabling rich text outputs.

• Launcher (launcher and full packages): Responsible for bootstrapping the agent execution environment, processing CLI arguments, and handling lifecycle events.

Usage Example

To run this application, after building the binary (e.g., myapp), invoke it with optional command-line arguments for the launcher:

./myapp --some-flag

The output sequence will be generated by the sequential agent which runs two sub-agents in order. Each sub-agent yields a greeting message with its ID.

Diagram: Structure and Workflow of main.go

flowchart TD
main["main()"]
myAgent1["myAgent{id:1}"]
myAgent2["myAgent{id:2}"]
agent1["agent.Agent (my_custom_agent_1)"]
agent2["agent.Agent (my_custom_agent_2)"]
seqAgent["sequentialagent.Agent (sequential_agent)"]
launcher["Launcher (full.Launcher)"]
main --> myAgent1
main --> myAgent2
myAgent1 --> agent1
myAgent2 --> agent2
agent1 --> seqAgent
agent2 --> seqAgent
seqAgent --> launcher
launcher -->|Execute| seqAgent
classDef agent fill:#f9f,stroke:#333,stroke-width:1px
class myAgent1,myAgent2,agent1,agent2,seqAgent agent

This flowchart depicts the main components and their relationships:

• The main function creates two myAgent instances with different IDs.

• These instances are wrapped as agent.Agent implementations.

• The two agents are aggregated into a sequentialagent.Agent.

• The full.Launcher executes the sequential agent according to the CLI and lifecycle.

• Data flows from individual agents to the sequential agent and then into the launcher execution.

References to Related Topics

• The use of agent.InvocationContext and event streaming relates to Agent Invocation Context.

• The sequential composition of agents corresponds to Sequential Agent.

• Agent creation and lifecycle management align with AI Agent Framework and Agent Lifecycle and Callbacks.

• The launcher integration connects with REST API and Web Launchers.

• The iterator pattern used in Run method leverages concepts in Agent Execution Runner.

This file is a practical example of composing agents and launching them within the AI agent framework ecosystem.