superbizon007/plan-self-ask-agent

By superbizon007

•Updated 4 months ago

Planning agent that produces a validated JSON execution plan

Image

Machine learning & AI

482

Overview Tags

superbizon007/plan-self-ask-agent repository overview

⁠plan-self-ask-agent

Planning agent that produces a validated JSON execution plan (step_graph DAG + agent assignments) from a user request and a list of available A2A agent cards.

Exposes:

A2A JSON-RPC API (Google Agent-to-Agent protocol)
OpenAI-compatible /v1/chat/completions endpoint

⁠Build

Build from inside this directory (apps/plan_self_ask_agent/). The shared packages/a2a_agent package is passed in as a named build context using Docker BuildKit's --build-context flag (available in Docker Desktop and Docker Engine ≥ 23).

# From apps/plan_self_ask_agent/
docker build \
  --build-context a2a_agent=../../packages/a2a_agent \
  -t plan-self-ask-agent:latest \
  .

⁠Run

⁠Minimal (no auth, plain HTTP)

docker run --rm \
  -e LLM_URL=https://api.openai.com/v1 \
  -e LLM_API_KEY=sk-... \
  -e LLM_MODEL=gpt-4o \
  -p 8080:8080 \
  plan-self-ask-agent:latest

⁠With trajectory recording

Writes per-step LLM request/response JSON files to a directory on the host:

docker run --rm \
  -e LLM_URL=https://api.openai.com/v1 \
  -e LLM_API_KEY=sk-... \
  -e LLM_MODEL=gpt-4o \
  -e TRAJECTORY_DIR=/trajectories \
  -v /tmp/trajectories:/trajectories \
  -p 8080:8080 \
  plan-self-ask-agent:latest

Each task creates TRAJECTORY_DIR/<task_id>/<timestamp>/ with:

turn_0000/llm_N_request.json / llm_N_response.json — self-ask iterations
turn_0001/llm_N_request.json / llm_N_response.json — graph build attempts
turn_0002/llm_0_request.json / llm_0_response.json — summary LLM call
summary.md — plan id, summary text, and assumptions

⁠With API key authentication

docker run --rm \
  -e LLM_URL=https://api.openai.com/v1 \
  -e LLM_API_KEY=sk-... \
  -e LLM_MODEL=gpt-4o \
  -e API_KEY=my-secret-token \
  -p 8080:8080 \
  plan-self-ask-agent:latest

All requests (except /health and /.well-known/agent.json) must then include:

Authorization: Bearer my-secret-token

⁠Custom port

docker run --rm \
  -e LLM_URL=https://api.openai.com/v1 \
  -e LLM_API_KEY=sk-... \
  -e PORT=9090 \
  -p 9090:9090 \
  plan-self-ask-agent:latest

⁠Environment variables

Variable	Default	Description
`LLM_URL`	`https://api.openai.com/v1`	OpenAI-compatible base URL
`LLM_API_KEY`	(empty)	API key for the LLM provider
`LLM_MODEL`	`gpt-4o`	Model name
`API_KEY`	(empty)	Bearer token for inbound auth (optional)
`PORT`	`8080`	Port the server listens on
`TRAJECTORY_DIR`	(disabled)	Directory to write per-task LLM trajectory files

⁠Health check

curl http://localhost:8080/health
# {"status":"ok","agent":"plan-self-ask-agent"}

⁠Usage

Send the input payload as a JSON string in the user message.

⁠OpenAI-compatible endpoint

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "{\"request\": \"Research AI trends and write a report\", \"available_agents\": [{\"name\": \"Research Agent\", \"url\": \"https://research.example.com/\", \"description\": \"Searches the web and summarises findings\"}, {\"name\": \"Writer Agent\", \"url\": \"https://writer.example.com/\", \"description\": \"Writes structured reports\"}]}"
      }
    ]
  }'

⁠A2A agent card

curl http://localhost:8080/.well-known/agent.json

⁠Input contract

{
  "request": "string (required)",
  "context": {
    "project": "string",
    "constraints": ["string"],
    "deadline": "string",
    "budget": "string"
  },
  "available_agents": [
    {
      "name": "string (required)",
      "url": "https://agent.example.com/ (required)",
      "description": "string (required)",
      "skills": [...]
    }
  ]
}

request and available_agents are required. Each agent card must have name, url, and description.

⁠Output contract

On success the agent returns a JSON plan:

{
  "plan_id": "uuid",
  "summary": "One paragraph summary",
  "assumptions": ["..."],
  "pipeline_stages": ["researchWithSelfAsk", "reportWriter"],
  "required_agents": [{"name": "...", "url": "...", "role": "...", "price_per_turn": 0.0}],
  "step_graph": {
    "is_dag": true,
    "entry_node_ids": ["S1"],
    "exit_node_ids": ["S2"],
    "nodes": [...],
    "edges": [...]
  },
  "execution_handoff": {"mode": "plan_only", "ready_for_orchestrator": true}
}

On error:

{
  "error": {
    "code": "VALIDATION_ERROR | PLANNING_FAILED | OUTPUT_SCHEMA_VIOLATION",
    "message": "string",
    "details": {}
  }
}

⁠MCP tools

The agent image exposes an MCP (Model Context Protocol) server on the same port as A2A at /mcp. Any MCP client — Claude Desktop, Cursor, Windsurf, ChatGPT Connectors, OpenAI Agents SDK — can list and invoke these tools using the pod's API_KEY as Bearer.

In production, Core proxies https://plan-self-ask-agent.agents.forfetch.ai/mcp → the worker pod's /mcp.

Tool (skill_id)	Description
`plan`	Generate a structured execution plan for a task

Input schemas are authored in apps/agents_mcp/app/seed.py. Skills without an explicit schema advertise a single {task: str} freeform parameter.

Tag summary

Recent tags

Content type

Image

Digest

sha256:0dbd31d19…

Size

139.5 MB

Last updated

4 months ago

docker pull superbizon007/plan-self-ask-agent