Using Hypercontext With Different Agents

Hypercontext exposes several agent layers so you can choose the right abstraction for the job.

Agent Overview

• TaskAgent for task-oriented prediction workflows
• MetaAgent for self-modification and tool use
• LLMClient for direct provider-backed interactions
• HyperContext for the top-level evolutionary loop

TaskAgent

Use TaskAgent when you want to solve a single task and extract a structured prediction.

Best for

• Benchmarks
• JSON prediction workflows
• Small deterministic task wrappers

Example

from hypercontext import TaskAgent
from hypercontext.agents.base import BaseAgentConfig

agent = TaskAgent(
    model="mock",
    config=BaseAgentConfig(model="mock", temperature=0.0, max_tokens=256),
)

The agent expects a domain and a task in its input payload.

MetaAgent

Use MetaAgent when you want the framework to inspect a repository, call tools, and propose edits.

Best for

• Self-modifying loops
• Refactoring assistance
• Repository-aware workflows

What It Can Do

• Read files
• Write files
• Append content
• Apply patches
• Run shell commands
• Analyze code structure

Example

from hypercontext import MetaAgent
from hypercontext.agents.base import BaseAgentConfig

agent = MetaAgent(
    model="mock",
    config=BaseAgentConfig(model="mock", temperature=0.0, max_tokens=512),
)

LLMClient

Use LLMClient when you want to talk to a provider directly or manage tool calls yourself.

Best for

• Provider experiments
• Tool-call loops
• Lower-level integrations

Example

from hypercontext import LLMClient
from hypercontext.providers.mock_provider import MockProvider

client = LLMClient(provider=MockProvider())
text, history, metadata = client.complete("hello")

For provider-specific setup recipes, see Provider recipes.

If you want the agent to use a named runtime preset from a YAML config, build the provider through Settings.create_provider() or the client through LLMClient.from_settings() and inject that into the agent.

HyperContext Orchestrator

Use HyperContext when you want the top-level evolution loop to run end to end.

Best for

• Automated generations
• Archive-driven improvement
• Run-directory based experiments

Example

from hypercontext import HyperContext

hc = HyperContext(output_dir="./runs/demo")
print(hc.run(max_generations=3))

Choosing The Right Layer

Use this rule of thumb:

1. If you need one answer, use TaskAgent.
2. If you need tool use and repository editing, use MetaAgent.
3. If you need direct provider access, use LLMClient.
4. If you need the whole loop, use HyperContext.

Mock-First Workflow

The easiest way to learn the system is to start with the mock provider:

1. Build your workflow against MockProvider.
2. Verify the prompts, tool calls, and output shape.
3. Swap in a real provider later.

The repo's examples/python/agent_tooling_demo.py shows that flow in one place.