microsoft--agent-framework/python/samples/02-agents/harness/build_your_own_claw

Build your own claw and agent harness — Python samples

Runnable Python samples for the "Build your own claw and agent harness with Microsoft Agent Framework" blog series. Each step builds a personal finance / investing assistant on top of create_harness_agent, reusing the shared harness console package in the parent harness/ directory.

• Part 1 — claw_step01_meet_your_claw.py — the minimal harness.
• Part 2 — claw_step02_working_with_data.py — file access, approvals, and durable memory.
• Part 3 — claw_step03_scaling_capabilities.py — skills, shell, CodeAct, and background agents.

Prerequisites

1. A Microsoft Foundry project with a deployed model.
2. Azure CLI installed and authenticated (az login).

Environment variables

export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project"
export FOUNDRY_MODEL="your-model-deployment-name"

---

Part 1 — Meet your claw

Builds the foundation of the assistant on top of create_harness_agent.

What this sample demonstrates

• create_harness_agent — a factory that builds a batteries-included agent: function invocation, per-service-call history persistence, planning (TodoProvider + AgentModeProvider), and web search.
• A custom function tool — get_stock_price, exposing local data to the agent. Prices are illustrative mock data, not real quotes.
• Web search — provided automatically by the harness for market news and commentary.
• Planning & modes — the agent breaks a multi-step request ("review my watchlist") into a todo list and switches between plan and execute modes.
• Shared harness console — interactive streaming UI (reused from the parent harness/console package) with /todos, /mode, and /exit commands.

Running

# From the repository root, using a PEP 723 compatible runner:
uv run python/samples/02-agents/harness/build_your_own_claw/claw_step01_meet_your_claw.py

What to expect

The sample starts an interactive loop. Try these in order:

1. /mode execute — switch out of the default plan mode; quick lookups don't need a plan.
2. What's the price of MSFT? — the agent calls the get_stock_price tool.
3. Any recent news on NVDA? — the agent uses web search.
4. Add MSFT, NVDA and SPY to my watch list — saved to watchlist.md in the session's memory.
5. /mode plan — switch back to plan mode for a bigger, multi-step task.
6. Review my watchlist and recommend some stocks to add — the agent plans, then executes. Type /todos to see the list and /mode to inspect the current mode.

---

Part 2 — Working with your data, safely

Teaches the assistant to work with your data safely.

What this sample demonstrates

• File access — the agent reads a pre-populated working/portfolio.csv and writes reports with the file_access_* tools. File access is on by default; the sample points its store at the sample's working/ folder via create_harness_agent(file_access_store=...).
• Approvals — file-access tools require approval by default, but the sample wires the built-in read_only_tools_auto_approval_rule so reads/lists/searches are frictionless while saving and deleting still pause for approval. The place_trade tool is marked approval_mode="always_require", so the harness asks you to approve or deny before any trade runs. The trade is simulated.
• Durable memory, two ways:
  • File memory (coarse-grained, explicit) — the agent reads/writes files such as watchlist.md. File memory is on by default; its files live on disk under {cwd}/agent-file-memory/<session-id>/, so they persist across runs on this machine. A new session starts empty; use /session-export and /session-import to preserve the session id so a relaunch re-links to its memory files (no fixed folder or owner id required).
  • Foundry memory (fine-grained, automatic) — Microsoft Foundry extracts durable facts from the conversation. Opt-in; see below.

Additional environment variables (optional — enable Foundry memory)

export FOUNDRY_MEMORY_STORE="claw-finance-memory"
export FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"

When these are not set, the sample runs with file memory only and prints a note.

Running

uv run python/samples/02-agents/harness/build_your_own_claw/claw_step02_working_with_data.py

What to expect

Try these in order (the sample starts in execute mode — quick lookups don't need a plan):

1. What's in my portfolio? — the agent reads portfolio.csv with the file_access tools.
2. Write me a short report on my portfolio and save it. — the agent writes a Markdown file under working/; saving is a write, so you are prompted to approve before the file is created.
3. I'm a conservative investor saving for a house in two years. — a durable fact (recalled later by Foundry memory when enabled).
4. Buy 10 shares of MSFT. — the agent calls place_trade; you are prompted to approve or deny before it runs.
5. Add SPY to my watchlist. — saved to watchlist.md in file memory.

Foundry memory (when enabled) recalls facts about you in any new session. File memory (the watchlist) lives on disk keyed by session id, so /session-export before you quit and /session-import after relaunching to re-link the relaunched session to its files, then ask "What's on my watchlist?" or "What do you know about me?".

Part 3 — Scaling its capabilities

Makes the assistant more capable along four axes.

What this sample demonstrates

• Skills — finance know-how (valuation, risk-scoring) is packaged as discoverable SKILL.md files under skills/, which the agent loads on demand. The sample builds a FileSkillsSource(..., script_runner=subprocess_script_runner) so the skills' Python scripts can run. Optionally folds in centrally-managed Foundry skills served from a Foundry Toolbox MCP endpoint via MCPSkillsSource (opt-in; see below).
• Shell — a LocalShellTool confined to the trade-confirmation vault (working/confirmations/) lets the agent tidy the accumulated confirmation files (reorganize into year/month, rename to YYYY-MM-DD_TICKER_BUY|SELL.txt). Guarded by a ShellPolicy deny-list and a confined working directory; left at the default approval_mode="always_require" so each command is surfaced for approval.
• CodeAct — a MontyCodeActProvider gives the agent a sandboxed, cross-platform Python interpreter to crunch portfolio numbers by writing and running code.
• Background agents — a lean, web-search-only TickerResearchAgent is registered via create_harness_agent(background_agents=[...]), so the main agent can fan out per-ticker research concurrently and aggregate the findings.

Additional environment variables (optional)

# Enable centrally-managed Foundry skills (Foundry Toolbox MCP endpoint URL):
export FOUNDRY_TOOLBOX_MCP_SERVER_URL="https://<your-project>.services.ai.azure.com/.../toolboxes/<toolbox>/mcp?api-version=v1"

When this is not set, the sample runs with the local file skills only, and prints a note.

Running

uv run python/samples/02-agents/harness/build_your_own_claw/claw_step03_scaling_capabilities.py

What to expect

Try these in order (the sample starts in execute mode — quick lookups don't need a plan):

1. Value MSFT for me. — the agent loads the valuation skill and follows its instructions (reading references and running its script).
2. Score the risk of my portfolio. — the agent reads portfolio.csv and loads the risk-scoring skill.
3. /mode plan, then Tidy up my trade confirmations. — switching to plan mode first makes the agent inspect working/confirmations/ and propose a reorganization plan before touching anything; once you approve it switches to execute and uses the shell to reorganize and rename the files, prompting you to approve each command.
4. Work out the total value of my portfolio. — the agent writes and runs Python via CodeAct.
5. Research MSFT, NVDA and SPY and summarize the latest news. — the agent fans the tickers out to the background research agent and aggregates the results.
6. What's the capital of France? — with a financial-agent-rules skill published to your Foundry toolbox and Foundry skills enabled (FOUNDRY_TOOLBOX_MCP_SERVER_URL), the agent loads it, recognizes the question is off-topic, and politely declines, steering you back to finance.

See the Part 3 blog post for more on the financial-agent-rules skill — including the SKILL.md to publish to your Foundry toolbox.