README
¶
Agent Core & Orchestration (pkg/core/tools/agent)
This directory contains the high-level tools that govern Falcon's "brain" and autonomous testing workflows.
Primary Tools (5)
memory
Recall and save project-specific knowledge (base URLs, auth patterns, API schemas) across sessions.
action: recall— Load facts from.falcon/memory.jsonandfalcon.mdaction: save— Save a single fact to.falcon/memory.jsonaction: update_knowledge— Update the.falcon/falcon.mdknowledge base (auto-validated)action: forget— Remove a factaction: list— View all facts
Mandatory on session start:
ACTION: memory({"action":"recall"})
run_tests
Execute test scenarios from the spec (merged: previously ran_tests + run_single_test).
- Run all scenarios:
run_tests({"scenarios": [...], "base_url": "..."}) - Run single scenario:
run_tests({"scenarios": [...], "base_url": "...", "scenario": "test_name"})
Writes validated report to .falcon/reports/unit_report_<timestamp>.md (or other type prefix).
auto_test
The autonomous testing engine. Orchestrates: analyze spec → generate test scenarios → run tests → fix failures.
- Input: endpoint URL
- Output: Test scenarios, report, proposed fixes
test_suite
Bundle multiple flows into a named, reusable test suite.
test_suite({"name": "user_auth_flow", "tests": [...]})→ saves to.falcon/flows/
Orchestration & Sessions
Session management is part of the mandatory workflow:
session_log({"action": "start"})at conversation startsession_log({"action": "end", "summary": "..."})before final answer
Session records persist to .falcon/sessions/ for audit trail and review.
Reports
All test runners automatically write validated reports to .falcon/reports/:
- Unit tests →
unit_report_<timestamp>.md - Functional tests →
functional_report_<timestamp>.md - Integration tests →
integration_report_<timestamp>.md - Security scans →
security_report_<timestamp>.md - Performance tests →
performance_report_<timestamp>.md
Validators (ValidateReportContent, ValidateFalconMD) ensure reports have meaningful content before returning success.
Usage
These tools are invoked by Falcon during autonomous cycles, or by the user when requesting test execution, knowledge updates, or multi-step workflows.
Example Prompts
Trigger these tools by asking:
- "Run a full autonomous test on the user service."
- "Remember that the base URL for the staging environment is
https://api.staging.example.com." - "Recall what we know about the auth endpoints."
- "Update the knowledge base with what we learned about the payment API."
- "Run the functional tests for the users endpoint."
- "Create a test suite that chains login → create user → delete user."
Documentation
¶
Overview ¶
Package agent provides agent memory and reporting tools for ZAP.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AutoTestParams ¶
type AutoTestTool ¶
type AutoTestTool struct {
// contains filtered or unexported fields
}
AutoTestTool orchestrates the full autonomous testing workflow: analyze endpoint → generate test scenarios via LLM → run all tests → diagnose failures.
func NewAutoTestTool ¶
func NewAutoTestTool( llmClient llm.LLMClient, a *debugging.AnalyzeEndpointTool, o *RunTestsTool, e *shared.TestExecutor, f *debugging.AnalyzeFailureTool, ) *AutoTestTool
func (*AutoTestTool) Description ¶
func (t *AutoTestTool) Description() string
func (*AutoTestTool) Name ¶
func (t *AutoTestTool) Name() string
func (*AutoTestTool) Parameters ¶
func (t *AutoTestTool) Parameters() string
type MemoryParams ¶
type MemoryParams struct {
Action string `json:"action"` // "save", "recall", "forget", "list", "update_knowledge"
Key string `json:"key,omitempty"` // Key for save/forget
Value string `json:"value,omitempty"` // Value for save
Category string `json:"category,omitempty"` // Category for save/list: "preference", "endpoint", "error", "project", "general"
Query string `json:"query,omitempty"` // Search query for recall
Section string `json:"section,omitempty"` // Section name for update_knowledge
Content string `json:"content,omitempty"` // Markdown content for update_knowledge
}
MemoryParams defines memory tool operations.
type MemoryTool ¶
type MemoryTool struct {
// contains filtered or unexported fields
}
MemoryTool provides persistent memory operations for the agent.
func NewMemoryTool ¶
func NewMemoryTool(store *core.MemoryStore) *MemoryTool
NewMemoryTool creates a new memory tool.
func (*MemoryTool) Description ¶
func (t *MemoryTool) Description() string
Description returns the tool description.
func (*MemoryTool) Execute ¶
func (t *MemoryTool) Execute(args string) (string, error)
Execute performs memory operations.
func (*MemoryTool) Parameters ¶
func (t *MemoryTool) Parameters() string
Parameters returns the tool parameter description.
type RunTestsParams ¶
type RunTestsParams struct {
Scenarios []shared.TestScenario `json:"scenarios"`
BaseURL string `json:"base_url"`
Category string `json:"category,omitempty"`
Categories []string `json:"categories,omitempty"`
Concurrency int `json:"concurrency,omitempty"`
TimeoutMs int `json:"timeout_ms,omitempty"`
ReportName string `json:"report_name,omitempty"` // e.g. "test_report_users_api"
}
RunTestsParams defines input for run_tests
type RunTestsTool ¶
type RunTestsTool struct {
// contains filtered or unexported fields
}
RunTestsTool executes multiple test scenarios
func NewRunTestsTool ¶
func NewRunTestsTool(falconDir string, testExecutor *shared.TestExecutor, reportWriter *shared.ReportWriter) *RunTestsTool
NewRunTestsTool creates a new run_tests tool
func (*RunTestsTool) Description ¶
func (t *RunTestsTool) Description() string
func (*RunTestsTool) Name ¶
func (t *RunTestsTool) Name() string
func (*RunTestsTool) Parameters ¶
func (t *RunTestsTool) Parameters() string
Source Files