​
RunAgent Go Client Documentation

The RunAgent Go client provides a simple interface for interacting with RunAgent services from Go applications.

​
Installation

go get github.com/runagent-dev/runagent-go

​
Client Creation

​
NewWithAddress

Creates a new client instance with a specific server address. 
func NewWithAddress(
    agentID string,
    agentName string,
    secure bool,
    host string,
    port int,
) (*Client, error)
Parameters:
  • agentID (string): Unique identifier for the agent
  • agentName (string): Name of the agent to invoke
  • secure (bool): Whether to use secure connection (HTTPS/TLS)
  • host (string): Server hostname or IP address
  • port (int): Server port number
Returns:
  • *Client: Configured client instance
  • error: Error if client creation fails

​
Client Methods

​
Run

Executes the agent with the provided parameters. 
func (c *Client) Run(ctx context.Context, params map[string]interface{}) (interface{}, error)
Parameters:
  • ctx (context.Context): Context for request timeout and cancellation
  • params (map[string]interface): Parameters to pass to the agent
Returns:
  • interface{}: Result from the agent execution
  • error: Error if execution fails

​
RunStream

Executes the agent with streaming response support. 
func (c *Client) RunStream(ctx context.Context, params map[string]interface{}) (*Stream, error)
Parameters:
  • ctx (context.Context): Context for request timeout and cancellation
  • params (map[string]interface): Parameters to pass to the agent
Returns:
  • *Stream: Stream instance for reading streaming responses
  • error: Error if stream creation fails

​
Stream Methods

The Stream type provides methods for reading streaming responses: 
func (s *Stream) Next(ctx context.Context) (interface{}, bool, error)
func (s *Stream) Close() error
  • Next: Returns the next data chunk, a boolean indicating if more data is available, and any error
  • Close: Closes the stream and releases resources

​
Close

Closes the client connection and releases resources. 
func (c *Client) Close() error

​
Examples

​
Example 1: Assistant Agent

This example shows how to use an assistant agent with a simple prompt. 
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/runagent-dev/runagent-go/pkg/client"
)

func main() {
    agentClient, err := client.NewWithAddress(
        "0a0765df-96d4-4884-90b8-74a6c3632010",
        "agno_assistant",
        true,
        "localhost",
        8453,
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer agentClient.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    result, err := agentClient.Run(ctx, map[string]interface{}{
        "prompt": "I want to know about chocolate",
    })
    if err != nil {
        log.Fatalf("Failed to run agent: %v", err)
    }

    fmt.Printf("Result: %v\n", result)
}

​
Example 2: Agno Assistant Streaming

This example shows how to use streaming with an Agno assistant agent. 
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/runagent-dev/runagent-go/pkg/client"
)

func main() {
    fmt.Println("=== Agno Assistant Streaming Example ===")

    // Create client for streaming entrypoint
    agentClient, err := client.NewWithAddress(
        "47d63228-cc58-43d9-a512-d3583f8bf019", // agentID
        "agno_stream",                          // entrypoint tag
        true,                                   // local
        "localhost",                            // host
        8450,                                   // port
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer agentClient.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    // Run streaming
    fmt.Println("Starting agno assistant stream...")
    stream, err := agentClient.RunStream(ctx, map[string]interface{}{
        "prompt": "I want to know about chocolate",
    })
    if err != nil {
        log.Fatalf("Failed to start stream: %v", err)
    }
    defer stream.Close()

    // Read from stream
    for {
        data, hasMore, err := stream.Next(ctx)
        if err != nil {
            log.Printf("Stream error: %v", err)
            break
        }

        if !hasMore {
            fmt.Println("Stream completed")
            break
        }

        fmt.Printf("Received: %v\n", data)
    }
}

​
Example 3: AG2 Invoke Agent

This example demonstrates using an AG2 invoke agent with message and turn limit parameters. 
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/runagent-dev/runagent-go/pkg/client"
)

func main() {
    agentClient, err := client.NewWithAddress(
        "7c8c54d0-297b-4c63-86ae-38326a882067",
        "ag2_invoke",
        true,
        "localhost",
        8453,
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer agentClient.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    result, err := agentClient.Run(ctx, map[string]interface{}{
        "message":   "The capital of bd is dhaka",
        "max_turns": 4,
    })
    if err != nil {
        log.Fatalf("Failed to run agent: %v", err)
    }

    fmt.Printf("Result: %v\n", result)
}

​
Example 4: AG2 Streaming

This example demonstrates using the streaming functionality with an AG2 agent. 
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/runagent-dev/runagent-go/pkg/client"
)

func main() {
    fmt.Println("=== AG2 Invoke Streaming Example ===")

    // Create client for streaming entrypoint
    agentClient, err := client.NewWithAddress(
        "6d9a6fb8-a58c-49de-92ef-cd64d53da932", // agentID
        "ag2_stream",                           // entrypoint tag
        true,                                   // local
        "localhost",                            // host
        8451,                                   // port
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer agentClient.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    // Run streaming
    fmt.Println("Starting AG2 invoke stream...")
    stream, err := agentClient.RunStream(ctx, map[string]interface{}{
        "message":   "The capital of bd is dhaka",
        "max_turns": 4,
    })
    if err != nil {
        log.Fatalf("Failed to start stream: %v", err)
    }
    defer stream.Close()

    // Read from stream
    for {
        data, hasMore, err := stream.Next(ctx)
        if err != nil {
            log.Printf("Stream error: %v", err)
            break
        }

        if !hasMore {
            fmt.Println("Stream completed")
            break
        }

        fmt.Printf("Received: %v\n", data)
    }
}

​
Common Parameters

Different agent types accept different parameters. Here are some common ones:

​
AG2 Invoke Agent Parameters

  • message (string): The message to send to the agent
  • max_turns (int): Maximum number of conversation turns

​
Assistant Agent Parameters

  • prompt (string): The prompt or question for the assistant