simple_acp 0.0.1

data/docs/client/sync-async.md

@@ -0,0 +1,308 @@
+# Sync & Async Execution
+
+SimpleAcp supports both synchronous and asynchronous execution patterns for different use cases.
+
+## Synchronous Execution
+
+### Basic Usage
+
+Wait for the run to complete:
+
+```ruby
+run = client.run_sync(
+  agent: "echo",
+  input: [SimpleAcp::Models::Message.user("Hello")]
+)
+
+puts run.status      # => "completed"
+puts run.output      # => [Message, ...]
+```
+
+### With Session
+
+```ruby
+client.use_session("conversation-123")
+
+run = client.run_sync(
+  agent: "chat",
+  input: [SimpleAcp::Models::Message.user("Hello")]
+)
+```
+
+### Handling Results
+
+```ruby
+run = client.run_sync(agent: "processor", input: [...])
+
+case run.status
+when "completed"
+  run.output.each do |message|
+    puts message.text_content
+  end
+when "failed"
+  puts "Error code: #{run.error.code}"
+  puts "Error message: #{run.error.message}"
+when "awaiting"
+  puts "Agent needs more input:"
+  puts run.await_request.message.text_content
+  # Handle await...
+end
+```
+
+### When to Use Sync
+
+- Quick operations (< few seconds)
+- Simple request-response patterns
+- When you need the result immediately
+- CLI tools and scripts
+
+## Asynchronous Execution
+
+### Basic Usage
+
+Start a run without waiting:
+
+```ruby
+run = client.run_async(
+  agent: "slow-processor",
+  input: [SimpleAcp::Models::Message.user("Large dataset")]
+)
+
+puts "Run started: #{run.run_id}"
+puts "Status: #{run.status}"  # => "in_progress"
+```
+
+### Polling for Completion
+
+```ruby
+run = client.run_async(agent: "processor", input: [...])
+
+# Poll until complete
+loop do
+  run = client.run_status(run.run_id)
+
+  puts "Status: #{run.status}"
+
+  break if run.terminal?
+  sleep 2
+end
+
+# Process results
+puts run.output if run.completed?
+puts run.error if run.failed?
+```
+
+### With Timeout
+
+```ruby
+run = client.run_async(agent: "processor", input: [...])
+timeout = Time.now + 300  # 5 minutes
+
+loop do
+  run = client.run_status(run.run_id)
+  break if run.terminal?
+
+  if Time.now > timeout
+    client.run_cancel(run.run_id)
+    raise "Operation timed out"
+  end
+
+  sleep 2
+end
+```
+
+### When to Use Async
+
+- Long-running operations
+- Background processing
+- When you can poll for results
+- Fire-and-forget patterns
+
+## Comparison
+
+| Aspect | Synchronous | Asynchronous |
+|--------|-------------|--------------|
+| Blocking | Yes | No |
+| Response time | Waits for completion | Immediate |
+| Use case | Quick operations | Long operations |
+| Error handling | Inline | Via polling |
+
+## Helper Patterns
+
+### Sync Wrapper for Async
+
+```ruby
+def run_with_timeout(client, agent:, input:, timeout: 60)
+  run = client.run_async(agent: agent, input: input)
+  deadline = Time.now + timeout
+
+  loop do
+    run = client.run_status(run.run_id)
+    return run if run.terminal?
+
+    if Time.now > deadline
+      client.run_cancel(run.run_id)
+      raise "Timeout waiting for run"
+    end
+
+    sleep 1
+  end
+end
+```
+
+### Async with Callback
+
+```ruby
+def run_async_with_callback(client, agent:, input:, &block)
+  Thread.new do
+    run = client.run_async(agent: agent, input: input)
+
+    loop do
+      run = client.run_status(run.run_id)
+      break if run.terminal?
+      sleep 1
+    end
+
+    block.call(run)
+  end
+end
+
+# Usage
+run_async_with_callback(client, agent: "processor", input: [...]) do |run|
+  puts "Completed: #{run.output}"
+end
+
+puts "Continuing while processing..."
+```
+
+### Batch Async Execution
+
+```ruby
+def run_batch(client, jobs)
+  # Start all jobs
+  runs = jobs.map do |job|
+    client.run_async(
+      agent: job[:agent],
+      input: job[:input]
+    )
+  end
+
+  # Wait for all to complete
+  completed = []
+
+  until runs.empty?
+    runs.each do |run|
+      updated = client.run_status(run.run_id)
+      if updated.terminal?
+        completed << updated
+        runs.delete(run)
+      end
+    end
+    sleep 1 unless runs.empty?
+  end
+
+  completed
+end
+
+# Usage
+results = run_batch(client, [
+  { agent: "processor", input: [...] },
+  { agent: "analyzer", input: [...] },
+  { agent: "formatter", input: [...] }
+])
+```
+
+## Resuming Awaited Runs
+
+Both sync and async support resuming:
+
+### Sync Resume
+
+```ruby
+run = client.run_sync(agent: "questioner", input: [...])
+
+if run.awaiting?
+  puts run.await_request.message.text_content
+
+  run = client.run_resume_sync(
+    run_id: run.run_id,
+    await_resume: SimpleAcp::Models::MessageAwaitResume.new(
+      message: SimpleAcp::Models::Message.user("My answer")
+    )
+  )
+end
+```
+
+### Async Resume
+
+```ruby
+run = client.run_async(agent: "questioner", input: [...])
+
+# ... later
+
+run = client.run_status(run.run_id)
+
+if run.awaiting?
+  # Resume asynchronously
+  run = client.run_async(
+    run_id: run.run_id,
+    await_resume: SimpleAcp::Models::MessageAwaitResume.new(
+      message: SimpleAcp::Models::Message.user("Answer")
+    )
+  )
+end
+```
+
+## Error Handling
+
+### Sync Errors
+
+```ruby
+begin
+  run = client.run_sync(agent: "processor", input: [...])
+
+  if run.failed?
+    handle_error(run.error)
+  end
+rescue Faraday::TimeoutError
+  puts "Request timed out"
+rescue Faraday::ConnectionFailed
+  puts "Connection failed"
+end
+```
+
+### Async Errors
+
+```ruby
+run = client.run_async(agent: "processor", input: [...])
+
+begin
+  loop do
+    run = client.run_status(run.run_id)
+    break if run.terminal?
+    sleep 1
+  end
+rescue => e
+  # Try to cancel on error
+  client.run_cancel(run.run_id) rescue nil
+  raise e
+end
+
+if run.failed?
+  handle_error(run.error)
+end
+```
+
+## Best Practices
+
+1. **Choose wisely** - Use sync for quick ops, async for long ones
+2. **Set timeouts** - Always have a maximum wait time
+3. **Handle all states** - Check for completed, failed, awaiting, cancelled
+4. **Cancel on error** - Clean up in-progress runs when errors occur
+5. **Poll appropriately** - Don't poll too frequently (1-2 second intervals)
+
+## Next Steps
+
+- Learn about [Streaming](streaming.md) for real-time updates
+- Explore [Session Management](sessions.md)
+- See [Events](../core-concepts/events.md) for event details

data/docs/core-concepts/agents.md

@@ -0,0 +1,253 @@
+# Agents
+
+Agents are the processing units in ACP that receive input messages and produce output messages. They encapsulate the logic for handling specific tasks.
+
+## What is an Agent?
+
+An agent is:
+
+- A named, registered handler on a server
+- Invoked with input messages
+- Returns output messages (synchronously or via streaming)
+- Optionally maintains state through sessions
+
+```mermaid
+graph LR
+    I[Input Messages] --> A[Agent Handler]
+    A --> O[Output Messages]
+    A --> E[Events]
+```
+
+## Registering Agents
+
+### Block Syntax
+
+The simplest way to create an agent:
+
+```ruby
+server = SimpleAcp::Server::Base.new
+
+server.agent("echo", description: "Echoes input back") do |context|
+  text = context.input.first&.text_content
+  SimpleAcp::Models::Message.agent("Echo: #{text}")
+end
+```
+
+### Agent Class
+
+For complex agents, use a class:
+
+```ruby
+class WeatherAgent
+  def call(context)
+    location = context.input.first&.text_content
+    weather = fetch_weather(location)
+    SimpleAcp::Models::Message.agent("Weather in #{location}: #{weather}")
+  end
+
+  private
+
+  def fetch_weather(location)
+    # API call or lookup
+  end
+end
+
+server.register("weather", WeatherAgent.new, description: "Gets weather")
+```
+
+### Agent Options
+
+Configure agent behavior:
+
+```ruby
+server.agent(
+  "processor",
+  description: "Processes various content types",
+  input_content_types: ["text/plain", "application/json"],
+  output_content_types: ["application/json"],
+  metadata: { version: "1.0", author: "Team" }
+) do |context|
+  # Handler logic
+end
+```
+
+## The Context Object
+
+Agents receive a `Context` object with:
+
+| Property | Description |
+|----------|-------------|
+| `input` | Array of input messages |
+| `session` | Current session (if any) |
+| `history` | Previous messages in session |
+| `state` | Session state data |
+| `run_id` | Current run identifier |
+| `agent_name` | Name of this agent |
+
+### Accessing Input
+
+```ruby
+server.agent("analyzer") do |context|
+  # Get first message's text
+  text = context.input.first&.text_content
+
+  # Process all messages
+  all_text = context.input.map(&:text_content).join("\n")
+
+  # Check for specific content types
+  json_parts = context.input.flat_map(&:parts).select(&:json?)
+
+  SimpleAcp::Models::Message.agent("Processed #{context.input.length} messages")
+end
+```
+
+### Using Session State
+
+```ruby
+server.agent("counter") do |context|
+  # Read state
+  count = context.state || 0
+
+  # Update state
+  count += 1
+  context.set_state(count)
+
+  SimpleAcp::Models::Message.agent("Count: #{count}")
+end
+```
+
+### Using History
+
+```ruby
+server.agent("summarizer") do |context|
+  # Access conversation history
+  previous = context.history.map(&:text_content).join("\n")
+
+  SimpleAcp::Models::Message.agent(
+    "Conversation so far:\n#{previous}\n\nNew: #{context.input.first&.text_content}"
+  )
+end
+```
+
+## Return Values
+
+### Single Message
+
+Return a single message:
+
+```ruby
+server.agent("simple") do |context|
+  SimpleAcp::Models::Message.agent("Response")
+end
+```
+
+### Multiple Messages
+
+Return an array of messages:
+
+```ruby
+server.agent("multi") do |context|
+  [
+    SimpleAcp::Models::Message.agent("First response"),
+    SimpleAcp::Models::Message.agent("Second response")
+  ]
+end
+```
+
+### Streaming with Enumerator
+
+For streaming responses, return an Enumerator:
+
+```ruby
+server.agent("streamer") do |context|
+  Enumerator.new do |yielder|
+    5.times do |i|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Message #{i + 1}")
+      )
+      sleep 0.5
+    end
+  end
+end
+```
+
+### Awaiting Input
+
+Request additional input mid-execution:
+
+```ruby
+server.agent("questioner") do |context|
+  Enumerator.new do |yielder|
+    # Ask for input
+    result = context.await_message(
+      SimpleAcp::Models::Message.agent("What is your name?")
+    )
+    yielder << result
+
+    # After resume, get the response
+    name = context.resume_message&.text_content
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Hello, #{name}!")
+    )
+  end
+end
+```
+
+## Agent Manifest
+
+Each agent has a manifest describing its capabilities:
+
+```ruby
+# Retrieved via client
+manifest = client.agent("echo")
+
+manifest.name                  # => "echo"
+manifest.description           # => "Echoes input back"
+manifest.input_content_types   # => ["text/plain"]
+manifest.output_content_types  # => ["text/plain"]
+manifest.metadata              # => {}
+```
+
+## Best Practices
+
+### Keep Handlers Focused
+
+Each agent should do one thing well:
+
+```ruby
+# Good: Single responsibility
+server.agent("translate") { |ctx| translate(ctx.input) }
+server.agent("summarize") { |ctx| summarize(ctx.input) }
+
+# Avoid: Kitchen sink agents
+server.agent("do_everything") { |ctx| ... }
+```
+
+### Handle Errors Gracefully
+
+```ruby
+server.agent("safe") do |context|
+  begin
+    process(context.input)
+  rescue StandardError => e
+    SimpleAcp::Models::Message.agent("Error: #{e.message}")
+  end
+end
+```
+
+### Use Descriptive Names
+
+```ruby
+# Good
+server.agent("weather-forecast", description: "Gets 7-day weather forecast")
+server.agent("text-summarizer", description: "Summarizes long text")
+
+# Avoid
+server.agent("agent1", description: "Does stuff")
+```
+
+## Next Steps
+
+- Learn about [Runs](runs.md) that execute agents
+- Explore [Sessions](sessions.md) for stateful agents
+- See the [Server Guide](../server/creating-agents.md) for advanced patterns