update

src/api.jl

@@ -13,7 +13,26 @@ using ..type, ..util, ..llmfunction
 
 """
 Send a message to the agent's input channel.
+
 Blocks if the input channel buffer is full (capacity 16 by default).
+The agent processes messages from `input_ch` in the background task.
+
+# Arguments
+- `agent::yiemAgent`: The agent instance to send a message to
+- `msg`: The message to send (any type accepted by the agent's processing pipeline)
+
+# Returns
+- The same `agent` instance for chaining
+
+# Notes
+- Use `take_response(agent)` to receive the agent's response after sending a message.
+- Use `follow_up(agent, msg)` to send messages while the agent is still processing.
+
+# Examples
+```jldoctest
+julia> run_agent(agent, "Hello!")
+yiemAgent(...)
+```
 """
 function run_agent(agent::yiemAgent, msg)
   put!(agent.input_ch, msg)
@@ -22,7 +41,23 @@ end
 
 """
 Take a response from the agent's output channel.
+
 Blocks until the agent sends a response.
+
+# Arguments
+- `agent::yiemAgent`: The agent instance to receive a response from
+
+# Returns
+- An `assistantMessage` instance representing the agent's response
+
+# Notes
+- Use `run_agent(agent, msg)` to send a message before calling this function.
+
+# Examples
+```jldoctest
+julia> response = take_response(agent)
+assistantMessage(...)
+```
 """
 function take_response(agent::yiemAgent)
   return take!(agent.output_ch)
@@ -30,8 +65,27 @@ end
 
 """
 Send a follow-up message while the agent is still processing.
-Follow-up messages are processed after all input_ch messages
+
+Follow-up messages are queued and processed after all `input_ch` messages
 and before any tool call results are sent.
+
+# Arguments
+- `agent::yiemAgent`: The agent instance to send a follow-up message to
+- `msg`: The follow-up message to send
+
+# Returns
+- The same `agent` instance for chaining
+
+# Notes
+- Use `run_agent(agent, msg)` for the primary message and `follow_up(agent, msg)` for additional
+  messages while the agent is processing.
+- Follow-up messages are buffered in a separate channel (capacity 32 by default).
+
+# Examples
+```jldoctest
+julia> follow_up(agent, "Also consider red wines")
+yiemAgent(...)
+```
 """
 function follow_up(agent::yiemAgent, msg)
   put!(agent.followUpQueue, msg)
@@ -40,7 +94,25 @@ end
 
 """
 Gracefully stop the agent.
-Sends a :shutdown signal, waits for the task to finish, then closes all channels.
+
+Sends a `:shutdown` signal to the input channel, waits for the background task to finish,
+then closes all channels (`input_ch`, `output_ch`, `followUpQueue`).
+
+# Arguments
+- `agent::yiemAgent`: The agent instance to stop
+
+# Returns
+- `nothing`
+
+# Notes
+- After calling `stop_agent`, the agent is no longer usable. A new agent must be created
+  for further interaction.
+- If the background task throws a `TaskFailedException`, it is rethrown.
+
+# Examples
+```jldoctest
+julia> stop_agent(agent)
+```
 """
 function stop_agent(agent::yiemAgent)
   put!(agent.input_ch, :shutdown)