Skip to content

Client Guide

The SimpleAcp client provides a clean interface for communicating with ACP servers over HTTP.

Overview

graph LR
    C[Client::Base] -->|HTTP| S[Server]
    C -->|SSE| S
    C --> A[Agents]
    C --> R[Runs]
    C --> SE[Sessions]

Quick Start

require 'simple_acp'

client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")

# Check connection
puts client.ping ? "Connected!" : "Failed"

# List agents
agents = client.agents
puts agents.agents.map(&:name)

# Run an agent
run = client.run_sync(
  agent: "echo",
  input: [SimpleAcp::Models::Message.user("Hello!")]
)
puts run.output.first.text_content

In This Section

  • Sync & Async

    Learn about synchronous and asynchronous execution

    Sync & Async

  • Streaming

    Handle real-time streaming responses

    Streaming

  • Session Management

    Maintain state across interactions

    Sessions

Client Configuration

Basic Setup

client = SimpleAcp::Client::Base.new(
  base_url: "http://localhost:8000"
)

With Timeout

client = SimpleAcp::Client::Base.new(
  base_url: "http://localhost:8000",
  timeout: 60  # seconds
)

With Headers

client = SimpleAcp::Client::Base.new(
  base_url: "http://localhost:8000",
  headers: {
    "Authorization" => "Bearer #{ENV['API_TOKEN']}",
    "X-Request-ID" => SecureRandom.uuid
  }
)

Discovery Methods

Health Check

if client.ping
  puts "Server is healthy"
else
  puts "Server unavailable"
end

List Agents

response = client.agents
response.agents.each do |agent|
  puts "#{agent.name}: #{agent.description}"
end

Get Agent Details

manifest = client.agent("echo")
puts manifest.name
puts manifest.description
puts manifest.input_content_types
puts manifest.output_content_types

Execution Methods

Synchronous

Wait for completion:

run = client.run_sync(
  agent: "processor",
  input: [SimpleAcp::Models::Message.user("Process this")]
)

case run.status
when "completed"
  puts run.output.first.text_content
when "failed"
  puts "Error: #{run.error.message}"
when "awaiting"
  # Handle await...
end

Asynchronous

Start and poll:

run = client.run_async(
  agent: "slow-processor",
  input: [SimpleAcp::Models::Message.user("Data")]
)

puts "Started: #{run.run_id}"

# Poll until complete
loop do
  run = client.run_status(run.run_id)
  break if run.terminal?
  sleep 1
end

puts run.output

Streaming

Real-time events:

client.run_stream(
  agent: "chat",
  input: [SimpleAcp::Models::Message.user("Hello")]
) do |event|
  case event
  when SimpleAcp::Models::MessagePartEvent
    print event.part.content
  when SimpleAcp::Models::RunCompletedEvent
    puts "\nDone!"
  end
end

Run Management

Get Status

run = client.run_status("run-id-here")
puts run.status

Get Events

events = client.run_events("run-id-here")
events.each do |event|
  puts event.type
end

Cancel Run

client.run_cancel("run-id-here")

Resume Awaited Run

run = client.run_resume_sync(
  run_id: "run-id-here",
  await_resume: SimpleAcp::Models::MessageAwaitResume.new(
    message: SimpleAcp::Models::Message.user("My response")
  )
)

Session Management

Use a Session

client.use_session("my-session-id")

# All runs now use this session
client.run_sync(agent: "chat", input: [...])
client.run_sync(agent: "chat", input: [...])

Clear Session

client.clear_session

Get Session Info

session = client.session("my-session-id")
puts session.history.length
puts session.state

Error Handling

begin
  run = client.run_sync(agent: "unknown", input: [...])
rescue SimpleAcp::Error => e
  puts "ACP Error: #{e.message}"
rescue Faraday::TimeoutError
  puts "Request timed out"
rescue Faraday::ConnectionFailed
  puts "Could not connect to server"
end

Best Practices

  1. Reuse clients - Create one client and reuse it
  2. Handle errors - Always catch and handle exceptions
  3. Use appropriate mode - Sync for quick ops, async/stream for long ops
  4. Manage sessions - Clear sessions when done
  5. Set timeouts - Configure appropriate timeout values

Next Steps