# Ad-hoc Agents

> Create agents on-the-fly without saving to workspace.

**URL:** https://inference.sh/docs/api/agent/adhoc
**Last updated:** 2026-09-18

---

Create agents on-the-fly without saving to workspace.

---

## Basic Usage

<div data-type="codegroup">

```python Python
from inferencesh import inference

client = inference(api_key="inf_your_key")

agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "You are a helpful assistant."
})

response = agent.send_message("Hello!")
print(response.text)
```

```typescript JavaScript
import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'You are a helpful assistant.'
});

const response = await agent.sendMessage('Hello!');
console.log(response.text);
```

</div>

---

## Configuration Options

<div data-type="codegroup">

```python Python
agent = client.agent({
    # Required - core_app with ref
    "core_app": {
        "ref": "infsh/claude-sonnet-4@latest",
        "setup": {...},          # One-time setup values (API keys, etc.)
        "input": {...}           # Default input values
    },

    # Optional
    "system_prompt": "You are a helpful assistant.",
    "tools": [...],              # Custom tools
    "skills": [...],             # On-demand context (see Skills section)
    "internal_tools": {...},     # Built-in tool settings
    "output_schema": {...},      # JSON Schema for structured output (uses finish tool)
    "max_tool_iterations": 10,   # Tool call limit
    "enable_autocomplete": True,

    # Model parameters (shorthand for core_app.input)
    "temperature": 0.7,
    "max_tokens": 4096,
})
```

```typescript JavaScript
interface AgentConfig {
  // Required - core_app with ref
  core_app: {
    ref: string;
    setup?: Record<string, any>;  // One-time setup values
    input?: Record<string, any>;  // Default input values
  };

  // Optional
  system_prompt?: string;
  tools?: Tool[];
  skills?: SkillConfig[];       // On-demand context
  internal_tools?: InternalToolsConfig;
  output_schema?: object;       // JSON Schema for structured output
  max_tool_iterations?: number;
  enable_autocomplete?: boolean;

  // Model parameters
  temperature?: number;
  max_tokens?: number;
}
```

</div>

---

## Core Apps

| App | Description |
|-----|-------------|
| `infsh/claude-sonnet-4` | Claude Sonnet 4 |
| `infsh/claude-haiku-35` | Claude 3.5 Haiku |
| `infsh/gpt-4o` | GPT-4o |
| `infsh/gpt-4o-mini` | GPT-4o Mini |

---

## With Tools

<div data-type="codegroup">

```python Python
from inferencesh import tool, string

weather_tool = (
    tool("get_weather")
    .describe("Get current weather")
    .param("city", string("City name"))
    .handler(lambda args: f"Weather in {args['city']}: 72°F, Sunny")
    .build()
)

agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "You help with weather info.",
    "tools": [weather_tool]
})

response = agent.send_message("What's the weather in Paris?")
```

```typescript JavaScript
import { tool, string } from '@inferencesh/sdk';

const weather = tool('get_weather')
  .describe('Get current weather')
  .param('city', string('City name'))
  .handler(args => `Weather in ${args.city}: 72°F, Sunny`)
  .build();

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  tools: [weather]
});
```

</div>

---

## Skills

Skills are reusable packages of context that agents can load on-demand via the `skill_get` tool. Instead of putting everything in the system prompt, define skills that the agent retrieves when needed.

<div data-type="codegroup">

```python Python
agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "You are a helpful code assistant.",
    "skills": [
        # Inline content
        {
            "name": "code-review",
            "description": "Guidelines for reviewing pull requests",
            "content": "# Code Review\n\nWhen reviewing code, check for:\n1. Security issues\n2. Performance..."
        },
        # URL-based (fetched and cached)
        {
            "name": "api-docs",
            "description": "API documentation",
            "url": "https://example.com/skills/api-docs.md"
        }
    ]
})
```

```typescript JavaScript
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'You are a helpful code assistant.',
  skills: [
    // Inline content
    {
      name: 'code-review',
      description: 'Guidelines for reviewing pull requests',
      content: '# Code Review\n\nWhen reviewing code, check for:\n1. Security issues\n2. Performance...'
    },
    // URL-based (fetched and cached)
    {
      name: 'api-docs',
      description: 'API documentation',
      url: 'https://example.com/skills/api-docs.md'
    }
  ]
});
```

</div>

The agent sees available skills in the `skill_get` tool description and loads full content only when relevant. See [Internal Tools](/docs/api/agent/internal-tools) for more details.

---

## Structured Output

Use `output_schema` to get typed JSON responses instead of free-form text. The agent uses the finish tool to return data matching your schema.

<div data-type="codegroup">

```python Python
agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "Extract structured data from text.",
    "output_schema": {
        "type": "object",
        "properties": {
            "summary": { "type": "string", "description": "Brief summary" },
            "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
            "confidence": { "type": "number", "description": "Confidence score 0-1" }
        },
        "required": ["summary", "sentiment", "confidence"]
    },
    "internal_tools": { "finish": True }
})
```

```typescript JavaScript
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'Extract structured data from text.',
  output_schema: {
    type: 'object',
    properties: {
      summary: { type: 'string', description: 'Brief summary' },
      sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
      confidence: { type: 'number', description: 'Confidence score 0-1' }
    },
    required: ['summary', 'sentiment', 'confidence']
  },
  internal_tools: { finish: true }
});
```

</div>

See [Structured Output](/docs/api/agent/structured-output) for the full guide — schema helpers, use cases, and tips.

---

## Internal Tools

Enable built-in tools:

<div data-type="codegroup">

```python Python
agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "internal_tools": {
        "web_search": True,
        "code_execution": True,
        "image_generation": {
            "enabled": True,
            "app_ref": "infsh/flux@latest"
        }
    }
})
```

```typescript JavaScript
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  internal_tools: {
    web_search: true,
    code_execution: true,
    image_generation: {
      enabled: true,
      app_ref: 'infsh/flux@latest'
    }
  }
});
```

</div>