blades

A Blades workspace is organized around several key markdown files that define the identity, memory, and operational context of your AI assistant. These files allow you to curate the assistant's personality, knowledge, and long-term memory.

Core Identity and Context Files

• SOUL.md: Defines the assistant's identity, principles, and persona.
• USER.md: Contains information about the user the assistant is helping.
• AGENTS.md: Configures session startup procedures and behavioral rules.

Memory and Knowledge Files

• MEMORY.md: Stores long-term, curated memory.
• memory/: A directory containing daily session logs.
• knowledges/: A directory for domain-specific reference files.

Operational Files

• TOOLS.md: Contains local setup notes (e.g., SSH configurations, device access).
• HEARTBEAT.md: A task list for proactive check-ins.

Workspace Configuration

To ensure the assistant operates correctly, you should maintain an IDENTITY.md file in your workspace that specifies your Home directory, Workspace directory, and the Model used (as configured in agent.yaml).

When a recipe defines sub_agents, you must specify an execution mode. This determines how the sub-agents are orchestrated:

1. sequential: Sub-agents run one after another. Use output_key in a sub-agent to save its result to the session state, which can then be accessed by subsequent sub-agents using {{.output_key}}. In this mode, the parent's instruction and output_key are ignored.
2. parallel: Sub-agents run concurrently. Outputs are written to session state independently. There are no data dependencies between steps.
3. tool: Each sub-agent is treated as a tool. The parent agent's LLM decides when to call them based on their name and description. Sub-agent output_key is not supported in this mode. Function tools and sub-agent tools are merged.
4. loop: Sub-agents run repeatedly up to max_iterations (default: 10). The loop terminates if a sub-agent calls the exit tool or if the iteration limit is reached. In this mode, the parent's instruction and output_key are ignored.

# Example: Sequential execution passing data
execution: sequential
sub_agents:
  - name: syntax-checker
    instruction: Check the {{.language}} code for syntax errors.
    output_key: syntax_report
  - name: quality-reviewer
    instruction: Review code quality. Syntax report: {{.syntax_report}}
    output_key: quality_report

Blades uses a decoupled architecture where different components are orchestrated by an Agent:

• Agent: The core coordinator. It integrates ModelProvider, Tool, Memory, and Middleware to understand intent and execute tasks. It implements the Agent interface, allowing it to be used in Chains or as part of a Flow.
• ModelProvider: An abstraction layer (adapter) that translates framework requests into specific LLM API formats (e.g., OpenAI, Gemini) and back. This allows you to switch models without changing your agent logic.
• Tool: External capabilities (APIs, databases, file systems) that an Agent can invoke. Tools use an InputSchema to guide the LLM on how to generate correct parameters and a Handle function to execute the logic.
• Flow: A mechanism to orchestrate multiple Agent components, where the output of one agent serves as the input for the next, enabling multi-step reasoning.

// Agent is the core interface for all executable components
type Agent interface {
    Name() string
    Description() string
    Run(context.Context, *Invocation) Generator[*Message, error]
}

// ModelProvider abstracts the LLM interaction
type ModelProvider interface {
    Generate(context.Context, *ModelRequest, ...ModelOption) (*ModelResponse, error)
    NewStreaming(context.Context, *ModelRequest, ...ModelOption) (Generator[*ModelResponse])
}

Claude can automatically execute tools defined in the blades.Tool struct. When a tool is provided in the ModelRequest, the client handles the iterative loop: calling the tool, processing the result, and returning the final response to the user.

// Define a tool
weatherTool := &blades.Tool{
	Name:        "get_weather",
	Description: "Get current weather for a location",
	Handle: func(ctx context.Context, arguments string) (string, error) {
		// Parse arguments and fetch weather
		return `{"temperature": 72, "condition": "sunny"}`, nil
	},
}

// Add tools to request
req := &blades.ModelRequest{
	Model: "claude-3-5-sonnet-20241022",
	Tools: []*blades.Tool{weatherTool},
	Messages: []*blades.Message{
		{
			Role: blades.RoleUser,
			Parts: []blades.Part{
				blades.TextPart{Text: "What's the weather in San Francisco?"},
			},
		},
	},
}

// Generate with automatic tool execution
resp, err := client.Generate(context.Background(), req)