update
This commit is contained in:
@@ -1,12 +1,16 @@
|
||||
# YiemAgent
|
||||
|
||||
Julia framework for building agents with tool use.
|
||||
Julia framework for building agents with tool use and MCP (Model Context Protocol) support.
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Install dependencies: `]add JSON, DataStructures, UUIDs, Dates, ...`
|
||||
2. Create a `yiemAgent` with `loadTools("src/tools")`
|
||||
3. Call `runAgent(agent, "message")` then `takeResponse(agent)`
|
||||
1. Install dependencies: `]add JSON, DataStructures, UUIDs, Dates, NATS, DataFrames`
|
||||
2. Create a callable `mcpServer` struct that communicates with an MCP server via NATS
|
||||
3. Create a `yiemAgent` with an LLM callable and MCP server:
|
||||
```julia
|
||||
agent = YiemAgent.yiemAgent(llmCall; mcpServer=mcpServer, agentEventSink=yourSink)
|
||||
```
|
||||
4. Call `runAgent(agent, message)` then `takeResponse(agent)`
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -14,21 +18,122 @@ Julia framework for building agents with tool use.
|
||||
src/
|
||||
├── YiemAgent.jl # Module entry point
|
||||
├── type.jl # Core types (messages, tools, agent state)
|
||||
├── utils.jl # Message formatting, validation
|
||||
├── utils.jl # Message formatting, context preparation, validation
|
||||
├── agentCore.jl # Agent loop, tool execution pipeline
|
||||
├── api.jl # Public API (runAgent, takeResponse, etc.)
|
||||
└── tools/
|
||||
├── registry.jl # Tool registry (loadTools, registerTool, listTools)
|
||||
├── getWeather.jl # Weather lookup tool
|
||||
├── getTime.jl # Time lookup tool
|
||||
├── writeTool.jl # Create new tool files (self-modifying)
|
||||
└── README.md # Tool development guide
|
||||
├── api.jl # Public API (runAgent, takeResponse, followUp, stopAgent)
|
||||
└── toolRegistry.jl # Tool store, MCP discovery, listTools registration
|
||||
```
|
||||
|
||||
## Tool Development
|
||||
## MCP Protocol
|
||||
|
||||
See `src/tools/README.md` for:
|
||||
- Tool anatomy (schema, execute, getTool)
|
||||
- Validation hooks
|
||||
- Agent loop lifecycle
|
||||
- Self-modifying tools (`writeTool`)
|
||||
YiemAgent uses JSON-RPC 2.0 for MCP communication. The `mcpServer` callable struct must implement:
|
||||
|
||||
```julia
|
||||
# tools/list — returns tool definitions
|
||||
mcpServer("tools/list") # → Dict("jsonrpc"=>"2.0", "id"=>1, "result"=>Dict("tools"=>[...], "nextCursor"=>...))
|
||||
|
||||
# tools/call — executes a tool
|
||||
mcpServer("tools/call", toolName, arguments) # → Dict("jsonrpc"=>"2.0", "id"=>2, "result"=>Dict("content"=>[...], "isError"=>...))
|
||||
```
|
||||
|
||||
Protocol error responses include `"error"` instead of `"result"`:
|
||||
```julia
|
||||
Dict("jsonrpc"=>"2.0", "id"=>2, "error"=>Dict("code"=>-32602, "message"=>"..."))
|
||||
```
|
||||
|
||||
### Implementing the MCP Server Client
|
||||
|
||||
You must provide a callable struct that communicates with your MCP server. Example using NATS:
|
||||
|
||||
```julia
|
||||
struct mcpServer
|
||||
natsConn::NATS.Connection
|
||||
topic::String
|
||||
senderID::String
|
||||
fileserver_url::String
|
||||
end
|
||||
|
||||
# tools/list implementation
|
||||
function (c::mcpServer)(method::String)
|
||||
if method != "tools/list"
|
||||
error("mcpServer: unexpected method '$method' (expected 'tools/list')")
|
||||
end
|
||||
|
||||
payload = Dict("jsonrpc" => "2.0", "id" => 1, "method" => method, "params" => Dict{String, Any}())
|
||||
payloads = [("payload", payload, "dictionary")]
|
||||
_, msg_envelope_json_str = msghandler.smartpack(
|
||||
c.topic, payloads;
|
||||
sender_id=c.senderID,
|
||||
msg_purpose="mcp_tools_list",
|
||||
fileserver_url=c.fileserver_url)
|
||||
|
||||
reply = NATS.request(c.natsConn, c.topic, msg_envelope_json_str, timeout=180)
|
||||
incoming_env = msghandler.smartunpack(String(reply.payload))
|
||||
return incoming_env["payloads"][1][2]
|
||||
end
|
||||
|
||||
# tools/call implementation
|
||||
function (c::mcpServer)(method::String, toolName::String, arguments::Dict{String, Any})
|
||||
if method != "tools/call"
|
||||
error("mcpServer: unexpected method '$method' (expected 'tools/call')")
|
||||
end
|
||||
|
||||
payload = Dict(
|
||||
"jsonrpc" => "2.0",
|
||||
"id" => 2,
|
||||
"method" => method,
|
||||
"params" => Dict(
|
||||
"name" => toolName,
|
||||
"arguments" => arguments
|
||||
)
|
||||
)
|
||||
payloads = [("payload", payload, "dictionary")]
|
||||
_, msg_envelope_json_str = msghandler.smartpack(
|
||||
c.topic, payloads;
|
||||
sender_id=c.senderID,
|
||||
msg_purpose="mcp_tool_call",
|
||||
fileserver_url=c.fileserver_url)
|
||||
|
||||
reply = NATS.request(c.natsConn, c.topic, msg_envelope_json_str, timeout=180)
|
||||
incoming_env = msghandler.smartunpack(String(reply.payload))
|
||||
return incoming_env["payloads"][1][2]
|
||||
end
|
||||
```
|
||||
|
||||
See `test/runtest.jl` for the complete working example.
|
||||
|
||||
## Tool Discovery
|
||||
|
||||
Tools are discovered dynamically via MCP server:
|
||||
|
||||
1. `listTool` is the only pre-registered tool
|
||||
2. When the LLM calls `listTools()`, tools are discovered from the MCP server and registered at runtime
|
||||
3. Supports pagination via `nextCursor` for large tool sets
|
||||
|
||||
## Agent API
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `runAgent(agent, msg)` | Send a message to the agent's input channel |
|
||||
| `takeResponse(agent)` | Block and take the agent's response from output channel |
|
||||
| `followUp(agent, msg)` | Send a follow-up message while agent is still processing |
|
||||
| `stopAgent(agent)` | Gracefully stop the agent and close channels |
|
||||
|
||||
## Agent Lifecycle
|
||||
|
||||
1. `yiemAgent()` spawns a background task (`_agentLoop`) listening on `inputChannel` and `followUpChannel`
|
||||
2. User messages enter via `runAgent()` or `followUp()`
|
||||
3. `_processMessage()` handles LLM calls, tool execution, and conversation history
|
||||
4. Tool execution follows three phases: `prepareToolCall` → `executePreparedToolCall` → `finalizeExecutedToolCall`
|
||||
5. `beforeToolCall`/`afterToolCall` hooks allow pre/post-processing of tool calls
|
||||
6. Tool `execute` functions can set `terminate=true` to stop the agent loop
|
||||
|
||||
## Hooks
|
||||
|
||||
| Hook | Signature | Purpose |
|
||||
|------|-----------|---------|
|
||||
| `prepareContext` | `(state, sink, llmCall) -> ctx` | Transform messages/context before LLM call |
|
||||
| `formatMsgForLLM` | `(ctx, sink) -> dict` | Convert agent context to LLM API format |
|
||||
| `beforeToolCall` | `(context, signal) -> result` | Block/allow tool execution |
|
||||
| `afterToolCall` | `(context, signal) -> result` | Post-process tool results |
|
||||
| `agentEventSink` | `(msg) -> nothing` | Callback for agent events/debug messages |
|
||||
|
||||
Reference in New Issue
Block a user